# dev-sync-agent-knowledge

**Repository Path**: wds-sync/dev-sync-agent-knowledge

## Basic Information

- **Project Name**: dev-sync-agent-knowledge
- **Description**: dev-sync-agent-knowledge 负责两类工作：维护公共能力并导出给 CodeGo；集中整理资料并更新 KBS 组件知识。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev-cooperyuan
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-08
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodeGo 公共知识工程

`dev-sync-agent-knowledge` 负责两类工作：**维护公共能力并导出给 CodeGo；集中整理资料并更新 KBS 组件知识。** 本工程由维护人员操作，不是在线服务，也不保存各组件的 Git 知识库。

本文提供项目导航；配置、参数、完整示例及异常处理见 [维护人员使用手册](usage_guide.md)。

## 1. 职责与流程

```text
公共配置、团队规范、固定规则、KBS 访问包
                    ▼
              维护与离线测试
                    ▼
         终端执行 Python 导出命令
                    ▼
       dev-sync-agent/.claude/ 公共快照
                    ▼
       CodeGo 回归 → 提交 → 打包安装

组件文档、用户手册、知数 QA、大圆故障
                    ▼
       Claude Code 执行 /knowledge-weekly
                    ▼
       读取来源 → 核实提炼 → 合并原主题
                    ▼
             KBS 组件正式知识
                    ▼
         组件研发检索使用、版本结束反补
```

团队规范和固定规则由维护人员编写，随插件发行，不参与自动晋升。组件处理稿和运行记录保留在本机，不导出，也不直接写入开发者仓库。

集中导入与组件 `sync-local` 共用 [主题同步约定](kbs-access/references/topic-sync.md) 和 [提炼写作规范](kbs-access/references/knowledge-writing/rules.md)。普通资料按主题分类，使用说明归入手册；完整规范及模板随访问包导出，无需外部 Skill 或在线资料。

正文按实际证据写作，保留真实别名、报错和参数，使用具体问题组织章节，并让操作与结论带上必要条件；关联链接须核实，更新保留原主题的有效内容。这些规则改善内容的可检索性与使用边界，不改变主题身份、标签或同步验收，也不代表 KBS 命中率已经提高。

## 2. 目录与配置

```text
dev-sync-agent-knowledge/
├── README.md                    # 项目导航
├── usage_guide.md               # 维护操作手册
├── CLAUDE.md                    # Claude 会话指引
├── requirements.txt             # Python 依赖
├── .claude/
│   ├── commands/                # knowledge-weekly、dayuan-receipt
│   └── skills/                  # 集中整理与机器人收件指引
├── config/                      # 组件登记、KBS 路由、来源与导出清单
├── team/                        # 人工维护的团队规范
│   ├── requirement/             # 需求
│   ├── design/                  # 设计
│   ├── development/             # 开发
│   ├── testing/                 # 测试
│   └── operations/              # 运维
│       └── policies/            # 固定风险分级、必测规则（JSON）
├── kbs-access/                  # 整目录导出的统一访问包
│   ├── config.json              # 实际连接配置，仅受控内部发行
│   ├── scripts/                 # 路由、客户端与主题同步
│   ├── references/              # 接口契约、能力与错误说明
│   │   └── knowledge-writing/   # 提炼规则、主题及手册模板
│   └── tests/                   # 客户端离线契约测试
├── scripts/                     # 导出、资料处理和收件工具
├── templates/                   # 周度摘要、正文与机器人模板
├── docs/                        # 内网初始化、批量导入与大圆收件说明
├── tests/                       # 工程离线回归
└── .runtime/                    # 本机来源、稿件与续办记录；不提交、不导出
```

| 配置文件 | 职责 | CodeGo 导出方式 |
|---|---|---|
| `config/catalog.yaml` | 稳定组件 ID、名称、别名、完整 Git 地址列表；一个组件可登记多个仓库 | 生成 `catalog-snapshot.yaml` |
| `config/kbs-routes.yaml` | 目标空间、组件目录、QA 来源及可选周度摘要目录 | 组件运行字段生成 `kbs-runtime.json`，集中来源不导出 |
| `config/source-routes.yaml` | QA 来源选择、周目录规则、大圆可信来源及本机路径 | 不导出 |
| `config/export-map.json` | 目录／文件复制、生成项及团队正文清单 | 驱动导出并生成来源清单 |
| `kbs-access/config.json` | 连接信息、调用身份 | 随访问包按既有授权受控分发，不输出密钥 |

目标知识空间为 `2100063511432581120`。组件须同时具备有效 Catalog 和 KBS 路由登记才启用；未启用时跳过来源读取及 KBS 调用，原研发流程继续。逐页 `knowledge_id`、`pageCode` 由工具维护，不填入公共配置。

Catalog 已登记 29 个组件及 47 个 Git 地址，路由已回填内网初始化后的正式根与交付参考根 ID。当前可直接按 [内网初始化与批量导入](docs/intranet-initialization.md) 第二节导入资料，无需重复创建组件根。后续新增登记仍以维护人员提供的映射为准，不从 `data/` 补充组件；治理目录不是初始化或导入前提。

`.runtime/` 包含原始资料和续办记录，不宜作为普通缓存清空。文件用途、协作交接和导出落点见手册第五、六章。

## 3. 常用命令

### 3.1 集中资料处理

在本工程根目录启动 **Claude Code**，在对话框输入以下命令。示例 `hpms` 和资料路径须替换为实际已登记组件及来源。

| 场景 | 命令 |
|---|---|
| 导入组件资料 | `/knowledge-weekly --import --type component-docs --component hpms --source "C:/materials/hpms"` |
| 导入用户手册 | `/knowledge-weekly --import --type usage-guide --component hpms --source "C:/materials/hpms/usage-guide.md"` |
| 导入历史 QA | `/knowledge-weekly --import --type zhishu-qa` |
| 导入历史故障 | `/knowledge-weekly --import --type incidents --source "C:/materials/incidents/2025"` |
| 按组件目录批量导入故障 | `/knowledge-weekly --import --type incidents --layout component-dirs --source "C:/materials/incidents"` |
| 整理指定周 QA 与大圆材料 | `/knowledge-weekly --week 2026-W37` |

`/knowledge-weekly` 是 Claude Code 命令，加载 `knowledge-curator` Skill 完成清洗、查证和合并；不是终端命令。多来源、石墨目录、失败续办及其他 AI 工具的使用方式见 [手册](usage_guide.md)。

`--layout component-dirs` 适用于四类导入：每个 `--source` 是本地父目录，一级目录名须精确匹配已启用组件 ID；可选 `--component` 只筛选目录，不改归属。故障汇总中受支持的记录按故障 ID 拆分审阅，同一事故或主题仍合并原页。所选范围完整处理，未知目录、根文件和解析失败均列明，不静默截断。

所有 `--import` 的批次、进度及处理结果只保存在 `.runtime/`，不上传处理报告、不依赖治理目录。QA／故障的业务待核实提醒已停用：不再创建、读取或清空 `pending/current`，旧页及旧状态保留。已知事实可以采用，未知原因保留为未知；无价值或无依据的主张不采用，但原始资料不删除。`--week` 保持既有来源采集，仅在配置了周度摘要路由时写摘要。

分组处理按来源累计，当前来源版本的最新有效完整性声明生效；已审阅数量不能掩盖尚未验收的上传。组件归属修正后可继续完成，错误尝试仍保留审计。`retry` 只验证原上传版本，来源或采用章节变化须重新准备、合并；完整续办规则见 [处理结果与异常续办](usage_guide.md#42-处理结果)。

周度整理由维护人员手动执行；现有机器人仅接收并落盘大圆消息，部署见 [大圆收件说明](docs/dayuan-setup.md)。内部工具分工：

| 工具 | 用途 |
|---|---|
| `knowledge_weekly.py prepare/apply` | 准备批次、执行 AI 整理结果；单独 prepare 不生成知识 |
| `knowledge_sources.py` | 枚举、核对和读取来源 |
| `knowledge_governance.py` | 在已配置路由时保存 QA／故障周度摘要 |
| `dayuan_inbox.py accept` | 校验消息分片，组装完整材料，不访问 KBS |

### 3.2 导出公共包

在**系统终端**执行；第一条导出，第二条只读核对：

```bash
/usr/bin/python3 "/Users/Admin/IdeaProjects/dev-sync-agent-knowledge/scripts/export-codego-kbs.py" --target "/Users/Admin/IdeaProjects/dev-sync-agent"
/usr/bin/python3 "/Users/Admin/IdeaProjects/dev-sync-agent-knowledge/scripts/export-codego-kbs.py" --target "/Users/Admin/IdeaProjects/dev-sync-agent" --check
```

导出源由脚本位置确定，目标为 CodeGo 仓库根目录。`kbs-access/` 递归复制，排除缓存、日志和环境文件；新增包内文件自动纳入。Catalog、运行路由和团队索引按清单生成；新增团队正文须登记 `team_documents`。

源、目标均无需先提交，源工程未跟踪文件也可导出。当前清单决定覆盖范围，目标同名文件会被覆盖；目标要保留的改动先回到本工程维护。旧导出记录缺失或损坏不阻止重建，不操作 Git 暂存区、不提交、不打包。导出后完成 CodeGo 回归并提交公共快照，其他维护者即可拉取后打包。

## 4. 环境与验证

使用 Python 3.9+ 和 Git，在工程根目录执行：

```bash
python -m pip install -r requirements.txt
python -m unittest discover -s tests -v
python -m unittest discover -s kbs-access/tests -v
```

安装和运行使用同一解释器；可按环境替换为 `python3` 或 `py -3`。离线测试使用假服务和临时工程，线上权限、石墨读取、机器人投递及完整 AI 流程仍需内网验收。

## 5. 参考文档

- [维护人员使用手册](usage_guide.md)：配置、完整参数、五类操作、导出与异常处理。
- [内网初始化与批量导入](docs/intranet-initialization.md)：登记真实目录、批量处理历史故障及可直接复用的提示词。
- [团队正文规范](team/README.md)：团队知识编写与发行。
- [KBS 统一访问契约](kbs-access/references/gateway-contract.md)：接入参数及续办边界。
- [客户端能力与实测记录](kbs-access/references/能力与接口契约.md)：接口实证。
- CodeGo `docs/knowledge-base/内网验收手册.md`：知识闭环验收。
- CodeGo `docs/CodeGo-开发回归与发版交接清单.md`：开发、回归与发布检查。

KBS 访问能力以本工程 `kbs-access/` 为唯一维护源，原 CodeGo `kbs/` 不再双份维护。诊断工具不用于绕过组件启用检查。