@xiaoailazy/coexistree-skills 0.2.0 → 0.2.1

package/README.md

@@ -2,6 +2,8 @@
 
 CoExistree **Agent Skills**：供 Cursor、Claude Code、Codex 等支持 `SKILL.md` 的 Agent 使用。与 [`@xiaoailazy/coexistree-cli`](../cli) 配合。
 
+用户文档：[docs/README.md](../../docs/README.md) · [Agent CLI](../../docs/user-guide/agent-cli.md)
+
 Skill **源文件**在本包的 `skills/` 目录；发布到 npm 后通过安装器复制到各 Agent 的技能目录。
 
 ## 安装
@@ -53,6 +55,7 @@ coexistree-skills-install --help
 | name | 用途 |
 |------|------|
 | `coexistree-config` | 首次 `config initial`、`config show` |
+| `coexistree-bootstrap` | 冷启动：代码库生成现状文档并导入知识树 |
 | `coexistree-task` | 产研任务：列表、拉取、上传 |
 | `coexistree-ask` | 知识树提问 |
 
@@ -64,7 +67,7 @@ coexistree-skills-install --help
 node packages/skills/scripts/install-skills.js --targets cursor --project
 ```
 
-**源文件以 `packages/skills/skills/` 为准**；`.cursor/skills/` 可继续 gitignore，由安装器生成。
+**源文件以 `packages/skills/skills/` 为准**；运行 `coexistree-skills-install` 同步到本机 Agent 技能目录。
 
 ## 发布
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiaoailazy/coexistree-skills",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Agent Skills for CoExistree (Cursor, Claude Code, Codex, and compatible agents)",
   "type": "module",
   "license": "MIT",

package/skills/coexistree-bootstrap/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: coexistree-bootstrap
+description: CoExistree 冷启动：从本地代码库生成系统现状 REQUIREMENT Markdown，经 task create + task apply 导入知识树。用于「初始化知识树」「老项目导入」「代码库生成现状文档」。
+---
+
+# coexistree bootstrap
+
+通过终端执行 **`coexistree`**（先 `npm install -g @xiaoailazy/coexistree-cli`）。前置：`coexistree config initial`。
+
+## 适用场景
+
+- 目标知识空间 **尚无 ACTIVE 系统知识树**（冷启动）。
+- 老项目缺少 PRD，需从**当前代码库**理解业务后写成现状说明，再导入 CoExistree。
+- **不要**用于已有 ACTIVE 树后的日常迭代（请用 `coexistree-task`）。
+
+---
+
+## 下游系统如何消费这篇文档（写作目标）
+
+上传后 CoExistree 会：
+
+1. **PageIndex**：按 Markdown `#` / `##` / `###` 切分文档树。
+2. **基线 LLM**：从章节归纳 **业务逻辑功能树**（MODULE / FEATURE），**不要**按文件夹或章节 1:1 镜像。
+
+**正文定位**：一篇给产品/业务读者也能读的 **系统现状说明**（由代码反推），不是设计说明书、不是接口文档。
+
+| 多写 | 少写或不写 |
+|------|------------|
+| 业务域、角色、场景、流程、规则、状态、协作边界 | 技术栈、框架、表名、API 路径、类名、部署、中间件 |
+| 「用户做什么 → 系统做什么 → 结果如何」 | 调用链、SQL、配置项、Topic 名 |
+| 模块/能力点的业务含义与边界 | 源码路径、证据锚点、审计式字段模板 |
+
+代码库仅作**理解业务的输入**；生成物里**不展示**技术实现细节。
+
+---
+
+## 流程总览
+
+1. `coexistree config show` → 记下 `system-code`
+2. **从代码理解业务**（内部笔记，见 §2）
+3. **生成业务导向 Markdown** → `docs/coexistree/<system-code>-system-as-is-requirement.md`
+4. **自检**（§4）→ 用户确认
+5. `task create` + `task apply`
+6. 知识树 / `ask` 验证
+
+---
+
+## 1. 检查配置
+
+```bash
+coexistree config show
+```
+
+---
+
+## 2. 从代码理解业务（内部探查，正文不写技术）
+
+在用户**当前工作区**阅读代码与现有文档，形成**业务笔记**（不写入最终 md）。遵守 `.gitignore`；**禁止**读取 `.env`、密钥及 `node_modules`/`target`/`dist` 等。
+
+### 2.1 弄清「这是个什么业务系统」
+
+| 问题 | 可从何处获得线索 |
+|------|------------------|
+| 为谁服务？解决什么业务问题？ | README、docs、命名、领域模型、界面文案 |
+| 与周边系统分工？（本仓库负责哪一块） | 集成调用、文档、包/模块命名（**理解即可，正文用业务语**） |
+| 有哪些主要**业务角色**？ | 权限、角色枚举、不同端（运营/用户/商家等） |
+
+### 2.2 划分业务域（4–10 个 `##`）
+
+不要按 `src/` 目录分章。按**业务_capability** 归纳，例如：
+
+- 会员与账户、商品与定价、交易与支付、履约与物流、运营与营销、报表与对账……
+
+每个域想清楚：
+
+- 管哪些**业务对象**（订单、合同、工单——用业务名）
+- 对外提供哪些**能力**（用业务动词）
+- 与哪些域**交接**（谁产生数据、谁消费）
+
+### 2.3 梳理端到端业务流程（2–5 条，全文重点）
+
+选真实业务链路，例如：注册开通、下单支付、审批发布、日终对账。
+
+每条流程用**业务步骤**记录：
+
+- 谁发起、在什么场景
+- 经过哪些业务环节（不用类名）
+- 关键业务状态变化
+- 异常/驳回/补偿的**业务含义**（若有）
+
+### 2.4 业务规则与约束
+
+从校验逻辑、状态机、注释、测试用例中提炼**业务规则**（如「未实名不可下单」「退款不得超过实付」），记入笔记，写入「业务规则与约束」章节。
+
+### 2.5 不确定与待澄清
+
+代码看不出的产品定义、疑似废弃流程、命名与真实业务不符等 → 记入「待澄清」，**不编造**。
+
+---
+
+## 3. 生成 Markdown（业务写作规程）
+
+**输出路径**：
+
+`docs/coexistree/<system-code>-system-as-is-requirement.md`
+
+**篇幅**：中文 **4000–10000 字**。至少 **4 个** 业务 `##` 域，每域 **≥2 个** `###` 能力点。
+
+### 3.1 格式
+
+| 规则 | 说明 |
+|------|------|
+| 标题 | 仅用 `#` `##` `###`；更深内容用段落或列表 |
+| 每个 `##` / `###` | 至少 1 段实质叙述，非空 |
+| 禁止 | 技术架构表、API 清单、表结构、类名墙、源码片段 |
+| 用语 | 产品/运营能读懂；必要时用业务对象名（「订单」「结算单」） |
+
+### 3.2 章节结构
+
+| 章节 | 作用 |
+|------|------|
+| 概述 | 系统定位、角色、业务域总览 |
+| 核心业务流程 | 跨域端到端流程（全文最重要之一） |
+| 各 `##` 业务域 | 域说明 + 多个 `###` 能力点 |
+| 业务协作与边界 | 域之间谁依赖谁、交接什么（业务语） |
+| 业务规则与约束 | 全局/跨域规则 |
+| 待澄清 | 从代码推不出或需产品确认的点 |
+
+**不要**设「技术架构」「对外接口」「数据与依赖」等技术向章节。
+
+### 3.3 每个 `###` 能力点
+
+用 **2–5 句** 或 **1 段 + 3–5 步业务步骤** 说明：
+
+- 谁在用、要解决什么业务问题  
+- 典型场景与结果  
+- 与同域其它能力的区别  
+
+可选一句：与哪一域协作。**不要**写 API、表、类、队列。
+
+### 3.4 文档模板
+
+```markdown
+# <系统显示名> — 业务现状说明
+
+> **文档性质**：由代码库反推的业务现状基线，非 PRD、非技术设计。  
+> **system_code**：`<system-code>`  
+> **归纳日期**：<YYYY-MM-DD>
+
+## 概述
+
+### 系统定位
+
+<为谁、解决什么业务问题、在业务版图中扮演什么角色，2–4 句>
+
+### 主要角色
+
+| 角色 | 典型诉求 |
+|------|----------|
+| <如 运营人员> | <…> |
+| <如 终端用户> | <…> |
+
+### 业务域总览
+
+| 业务域 | 一句话说明 |
+|--------|------------|
+| <域 A> | <…> |
+| <域 B> | <…> |
+
+（须覆盖下文每个业务 `##`）
+
+## 核心业务流程
+
+### <流程名，如「从下单到收货」>
+
+<1 段：场景与参与角色>
+
+1. <业务步骤>
+2. <业务步骤>
+3. <业务步骤>
+
+<可选：关键业务状态、常见例外情况，用业务语描述>
+
+### <流程 2>
+
+（至少 2 条；极简系统可 1 条，并在「待澄清」说明）
+
+## <业务域 A>
+
+<本域管什么业务对象、与邻域边界，1 段>
+
+### <能力点，如「提交订单」>
+
+<业务叙述：谁、何时、做什么、得到什么结果。>
+
+<可选：3–5 步业务子流程。>
+
+### <能力点 2>
+
+（每域至少 2 个 `###`）
+
+## <业务域 B>
+
+（全文至少 4 个此类 `##`，均为业务域名称）
+
+## 业务协作与边界
+
+<各域之间如何衔接：例如「支付域在订单确认后介入」「报表域只读交易结果」。用业务对象与事件描述，不写系统名/SDK。>
+
+## 业务规则与约束
+
+- <规则 1：业务语言>
+- <规则 2>
+- …
+
+## 待澄清
+
+- <需产品或业务方确认的点>
+```
+
+### 3.5 反模式（必须改写）
+
+| 反模式 | 应改为 |
+|--------|--------|
+| 技术栈、Spring、Kafka、表名、API 路径 | 删除或改成业务影响（如「异步通知用户」） |
+| 按源码目录分 `##` | 业务域 |
+| `### XxxController` / `### User表` | 业务能力名 + 业务叙述 |
+| 大段接口/字段列表 | 并入「业务协作」或删掉 |
+| 每个 `###` 只有一词 | 补足业务说明 |
+| 全文无端到端流程 | 补「核心业务流程」 |
+
+---
+
+## 4. 上传前自检
+
+全部为是再请用户确认：
+
+- [ ] 路径正确；文首有 `system_code`、日期
+- [ ] **无**技术架构/API/表/类/部署专章或大段列举
+- [ ] ≥4 个业务 `##`，每域 ≥2 个 `###`，均有业务叙述
+- [ ] 「核心业务流程」≥2 条（或 1 条且待澄清已说明）
+- [ ] 有「业务协作与边界」「业务规则与约束」「待澄清」
+- [ ] 通篇读感像**业务现状**而非技术文档
+- [ ] 无源码、无 `.env`/密钥
+
+向用户展示：**业务域总览表 + 自检结果**。
+
+---
+
+## 5. 导入知识树
+
+```bash
+coexistree task create \
+  --title "【初始化】系统现状（来自代码库）" \
+  --summary "coexistree-bootstrap；业务现状基线" \
+  docs/coexistree/<system-code>-system-as-is-requirement.md
+
+coexistree task apply --task-id <taskId>
+```
+
+---
+
+## 6. 验证
+
+- 知识树节点是否为**业务模块/能力**（而非技术组件）。
+- `coexistree ask --question "该系统有哪些核心业务域？各域做什么？"` 答案与文档一致。
+
+若节点过碎或像技术分层：合并 `###`、加强「业务域总览」与流程章，再重导。
+
+---
+
+## 失败处理
+
+| 现象 | 处理 |
+|------|------|
+| `apply_failed` | 检查文件非空、标题层级 |
+| LLM 错误 | 服务端 LLM 配置 |
+| 已有 ACTIVE 树 | 勿重复冷启动 |
+| 知识树偏技术 | 按 §3.5 改为业务表述后重导 |
+
+---
+
+## 与 coexistree-task 的分工
+
+| Skill | 用途 |
+|-------|------|
+| `coexistree-bootstrap` | 冷启动：理解业务 → 写业务现状 md → create → apply |
+| `coexistree-task` | 迭代产研：list / pull / upload 设计·用例 |

package/skills/coexistree-config/SKILL.md

@@ -7,6 +7,8 @@ description: CoExistree 配置管理：初始化 API 密钥与 system code、查
 
 通过终端执行 **`coexistree`**（先 `npm install -g @xiaoailazy/coexistree-cli`）。适用于 Cursor、Claude Code、Codex 等支持 Agent Skills 的环境。
 
+**知识空间** = 平台内 `system_code` 边界；术语见仓库 `docs/user-guide/glossary.md`。
+
 ## 首次配置（只需一次）
 
 在 Web **密钥管理** 开启 Agent 密钥并复制；确认目标系统的 **system code**。

package/skills/coexistree-task/SKILL.md

@@ -10,7 +10,7 @@ description: CoExistree 产研任务：创建、列表、拉取、上传文档
 ## 约定
 
 - **upload** 必须带 1 个 `.md` 路径；设计稿用 Agent 刚写完的文件，不确定则问用户。
-- **pull** 默认写入 `docs/superpowers/{prd|specs|testcases}/{suggestedBasename}-{prd|design|testcase}-{documentId}.md`。
+- **pull** 默认将文档保存到当前项目 `docs/` 下由 CLI 生成的路径（文件名含类型与 documentId）；具体规则见 `coexistree task pull --help`。
 - 文档不会自动进知识树；须在 Web 对任务「应用变更」。
 
 ## 命令