docs(claude): restructure documentation management and add feedback system

- Restructure §8 from "文档沉淀规则" to "文档管理规则" with 4 subsections
  - Add docs/ structure with features/ and knowledge-base/ directories
  - Add feature documentation template with 7 sections (概述/设计初衷/技术设计/预期作用/实际效果/演化路线/头脑风暴)
  - Add feature update trigger matrix (新增/修改/完成/问题/反馈)
  - Add documentation quality checklist
- Add §16
This commit is contained in:
iven
2026-03-16 13:54:03 +08:00
parent 8e630882c7
commit adfd7024df
44 changed files with 10491 additions and 248 deletions

View File

@@ -282,9 +282,63 @@ pnpm tsc --noEmit
---
## 8. 文档沉淀规则
## 8. 文档管理规则
凡是出现以下情况,应更新 `docs/openfang-knowledge-base.md` 或相关文档:
### 8.1 文档结构
```text
docs/
├── features/ # 功能全景文档
│ ├── README.md # 功能索引和优先级矩阵
│ ├── brainstorming-notes.md # 头脑风暴记录
│ ├── 00-architecture/ # 架构层功能
│ ├── 01-core-features/ # 核心功能
│ ├── 02-intelligence-layer/ # 智能层 (L4 自演化)
│ ├── 03-context-database/ # 上下文数据库
│ ├── 04-skills-ecosystem/ # Skills 生态
│ ├── 05-hands-system/ # Hands 系统
│ └── 06-tauri-backend/ # Tauri 后端
├── knowledge-base/ # 技术知识库
│ ├── openfang-technical-reference.md
│ ├── openfang-websocket-protocol.md
│ └── troubleshooting.md
└── WORK_SUMMARY_*.md # 工作日志
```
### 8.2 功能文档维护规范
**何时更新功能文档**
| 触发条件 | 更新内容 |
|---------|---------|
| 新增功能 | 创建新文档,填写设计初衷 |
| 功能修改 | 更新技术设计、预期作用 |
| 功能完成 | 更新实际效果、测试覆盖 |
| 发现问题 | 更新已知问题、风险挑战 |
| 用户反馈 | 更新用户反馈、演化路线 |
**功能文档模板**
```markdown
# [功能名称]
> **分类**: [架构层/核心功能/智能层/上下文数据库/Skills/Hands/Tauri]
> **优先级**: [P0-决定性 / P1-重要 / P2-增强]
> **成熟度**: [L0-概念 / L1-原型 / L2-可用 / L3-成熟 / L4-生产]
> **最后更新**: YYYY-MM-DD
## 一、功能概述
## 二、设计初衷(问题背景、设计目标、竞品参考、设计约束)
## 三、技术设计(核心接口、数据流、状态管理)
## 四、预期作用(用户价值、系统价值、成功指标)
## 五、实际效果(已实现、测试覆盖、已知问题、用户反馈)
## 六、演化路线(短期/中期/长期)
## 七、头脑风暴笔记(待讨论问题、创意想法、风险挑战)
```
### 8.3 知识库更新规则
凡是出现以下情况,应更新 `docs/knowledge-base/` 或相关文档:
- 新的协议坑 (REST/WebSocket)
- 新的握手/配置/模型排障结论
@@ -294,6 +348,16 @@ pnpm tsc --noEmit
原则:**修完就记,避免二次踩坑。**
### 8.4 文档质量检查清单
每次更新文档后,检查:
- [ ] 文件路径引用正确
- [ ] 技术术语统一
- [ ] ICE 评分已更新
- [ ] 成熟度等级已更新
- [ ] 已知问题列表已更新
---
## 9. 常见高风险点
@@ -407,3 +471,15 @@ docs(knowledge-base): capture OpenFang RBAC permission issues
- [ ] 插件从 TypeScript 改为 SKILL.md
- [ ] 添加 Hands/Workflow 相关 UI
- [ ] 处理 16 层安全防护的交互
---
## 16. 参考文档更新
- `docs/features/README.md` - 功能索引和优先级矩阵
- `docs/features/brainstorming-notes.md` - 头脑风暴记录
- `docs/knowledge-base/openfang-technical-reference.md` - OpenFang 技术参考
- `docs/knowledge-base/openfang-websocket-protocol.md` - WebSocket 协议
- `docs/knowledge-base/troubleshooting.md` - 排障指南
- `skills/` - SKILL.md 技能定义
- `hands/` - HAND.toml 自主能力包