Skip to content

Commit 08d89e0

Browse files
author
cuixiaoling
committed
docs: split bilingual readme and improve community metadata
1 parent b4525b6 commit 08d89e0

File tree

7 files changed

+177
-21
lines changed

7 files changed

+177
-21
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
name: Bug report
2+
description: Report a reproducible bug in adapter behavior
3+
title: "[Bug]: "
4+
labels: [bug]
5+
body:
6+
- type: textarea
7+
id: summary
8+
attributes:
9+
label: Summary
10+
description: What happened?
11+
validations:
12+
required: true
13+
- type: textarea
14+
id: steps
15+
attributes:
16+
label: Steps to reproduce
17+
description: Provide minimal input and command
18+
validations:
19+
required: true
20+
- type: textarea
21+
id: expected
22+
attributes:
23+
label: Expected behavior
24+
validations:
25+
required: true

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: Feature request
2+
description: Propose an enhancement aligned with skill boundaries
3+
title: "[Feature]: "
4+
labels: [enhancement]
5+
body:
6+
- type: textarea
7+
id: problem
8+
attributes:
9+
label: Problem
10+
description: What workflow is blocked today?
11+
validations:
12+
required: true
13+
- type: textarea
14+
id: proposal
15+
attributes:
16+
label: Proposal
17+
description: What should be added or changed?
18+
validations:
19+
required: true

‎.github/pull_request_template.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## Summary
2+
3+
## What changed
4+
5+
-
6+
7+
## Validation
8+
9+
- [ ] `pytest -q`
10+
- [ ] CLI demo command executed
11+
- [ ] Docs updated if interfaces changed

‎CODE_OF_CONDUCT.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Code of Conduct
2+
3+
This project follows a simple standard: be respectful, constructive, and professional.
4+
5+
- Be specific when reporting issues.
6+
- Focus on behavior and reproducible facts.
7+
- Assume good intent and avoid personal attacks.
8+
9+
Maintainers may moderate discussions and contributions that violate this policy.

‎CONTRIBUTING.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Contributing
2+
3+
## Setup
4+
5+
```bash
6+
python3 -m venv .venv
7+
source .venv/bin/activate
8+
pip install -e ".[dev]"
9+
pytest -q
10+
```
11+
12+
## Contribution Rules
13+
14+
- Keep behavior aligned with `SKILL.md` and `references/segmentation-rules.md`.
15+
- Preserve code/image/key-term fidelity.
16+
- Include tests for behavior changes in segmentation or preservation logic.
17+
- Update docs (`README.md`, `README.zh-CN.md`, examples) when interfaces change.

‎README.md‎

Lines changed: 23 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,32 @@
11
# mdf-material-adapter
22

3-
Production-ready adapter that turns noisy course transcripts/documents into stable lesson segmentation candidates for MarkdownFlow generation.
3+
[中文文档](./README.zh-CN.md)
44

5-
## 适用场景
5+
Production-ready adapter that transforms noisy transcripts or course docs into stable lesson segmentation candidates for MarkdownFlow generation while preserving code blocks, images, and key terms.
66

7-
- 逐字稿噪声高（口头填充词、重复句）但需要稳定切课。
8-
- 文档混合代码块、图片、术语，需要保真迁移到后续教学脚本。
9-
- 在 MarkdownFlow 课节生成前，需要一个中间结构层。
7+
## Use Cases
108

11-
## 非适用场景
9+
- Raw transcripts are noisy (filler words, repeated phrases) and need deterministic lesson splits.
10+
- Source material mixes prose, code blocks, and images that must be preserved.
11+
- You need a structured intermediate artifact before MarkdownFlow lesson script generation.
1212

13-
- 不适合用于改写课程结论或改变原始事实口径。
14-
- 不替代完整教学设计，不直接产出最终授课脚本。
15-
- 不做多模态 OCR 提取（仅处理文本中已有图片/代码标记）。
13+
## Non-Goals
1614

17-
## Quickstart
15+
- It does not rewrite course conclusions or alter factual claims.
16+
- It is not a full instructional design system and does not output final teaching scripts.
17+
- It does not perform OCR or extract text from binary assets.
18+
19+
## Quickstart (3 minutes)
1820

1921
```bash
20-
python -m venv .venv
22+
python3 -m venv .venv
2123
source .venv/bin/activate
22-
pip install -e .
24+
pip install -e ".[dev]"
2325
mdf-material-adapter --input examples/sample_input.md --output output.json
24-
python -m json.tool output.json | head -n 60
26+
python -m json.tool output.json | head -n 50
2527
```
2628

27-
## 输出 JSON 示例
29+
## JSON Output Example
2830

2931
```json
3032
{
@@ -48,30 +50,30 @@ python -m json.tool output.json | head -n 60
4850
"lesson_candidates": [
4951
{
5052
"lesson_id": "lesson-01",
51-
"core_question": "你认为这段的核心问题是什么？"
53+
"core_question": "What is the core learning question in this segment?"
5254
}
5355
]
5456
}
5557
```
5658

57-
## 设计：Skill Core + Adapters
59+
## Design: Skill Core + Adapters
5860

59-
- Skill Core (`src/mdf_material_adapter/core.py`): 去噪、语义分段、保真块索引、迁移线索。
60-
- CLI Adapter (`src/mdf_material_adapter/cli.py`): 文件输入输出，供脚本和流水线调用。
61+
- Skill Core (`src/mdf_material_adapter/core.py`): denoise, semantic segmentation, immutable block indexing, migration cues.
62+
- CLI Adapter (`src/mdf_material_adapter/cli.py`): file-in/file-out interface for scripts and pipelines.
6163
- Ecosystem Adapters:
6264
- OpenClaw: `tool.json` + `examples/openclaw_demo.md`
6365
- Claude: `examples/claude_function_calling.md`
6466
- Codex: `scripts/codex_task.md`
6567

66-
## 与 AI-Shifu 的关系
68+
## Relationship to AI-Shifu
6769

68-
该项目是 AI-Shifu 课程生产链路中的“资料适配”步骤之一，用于在正式教学脚本生成前提供稳定中间结构。
70+
This repository is one step in AI-Shifu's course production pipeline: adapting raw material before lesson-level script generation.
6971

7072
- Website: https://ai-shifu.com
7173

7274
## Development
7375

7476
```bash
75-
pip install -e .[dev]
77+
pip install -e ".[dev]"
7678
pytest -q
7779
```

‎README.zh-CN.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# mdf-material-adapter
2+
3+
[English README](./README.md)
4+
5+
一个面向生产的课程资料适配器：将噪声逐字稿/课程文档转换为可稳定切分课节的中间结构，并保留代码块、图片与关键术语。
6+
7+
## 适用场景
8+
9+
- 逐字稿噪声高（口头填充词、重复句），但需要稳定切课。
10+
- 文档混合代码、图片、术语，需要高保真迁移。
11+
- 在 MarkdownFlow 授课脚本生成前，需要结构化中间层。
12+
13+
## 非适用场景
14+
15+
- 不用于改写课程结论或改变事实口径。
16+
- 不替代完整教学设计，不直接产出最终授课脚本。
17+
- 不做 OCR 或二进制资源文本提取。
18+
19+
## 快速开始（3 分钟）
20+
21+
```bash
22+
python3 -m venv .venv
23+
source .venv/bin/activate
24+
pip install -e ".[dev]"
25+
mdf-material-adapter --input examples/sample_input.md --output output.json
26+
python -m json.tool output.json | head -n 50
27+
```
28+
29+
## 输出 JSON 示例
30+
31+
```json
32+
{
33+
"meta": {
34+
"adapter": "mdf-material-adapter",
35+
"version": "0.1.0",
36+
"segment_count": 4
37+
},
38+
"ordered_segments": [
39+
{
40+
"segment_id": "seg-001",
41+
"segment_type": "concept",
42+
"preserve_block": "no"
43+
},
44+
{
45+
"segment_id": "seg-002",
46+
"segment_type": "code",
47+
"preserve_block": "yes"
48+
}
49+
]
50+
}
51+
```
52+
53+
## 设计：Skill Core + Adapters
54+
55+
- Skill Core（`src/mdf_material_adapter/core.py`）：去噪、语义分段、保真块索引、迁移线索。
56+
- CLI Adapter（`src/mdf_material_adapter/cli.py`）：文件输入输出，便于流水线调用。
57+
- 生态适配：
58+
- OpenClaw：`tool.json` + `examples/openclaw_demo.md`
59+
- Claude：`examples/claude_function_calling.md`
60+
- Codex：`scripts/codex_task.md`
61+
62+
## 与 AI-Shifu 的关系
63+
64+
本项目是 AI-Shifu 课程生产链路中的“资料适配”步骤之一，用于在正式授课脚本生成前提供稳定中间结构。
65+
66+
- 官网：https://ai-shifu.com
67+
68+
## 开发
69+
70+
```bash
71+
pip install -e ".[dev]"
72+
pytest -q
73+
```

0 commit comments

Comments
 (0)