@house365/comate 0.9.24 → 0.9.25

package/skills/comate-gate/scaffold/docs/knowledge-base/README.md

@@ -1,47 +1,47 @@
-# 知识库 (Knowledge Base)
-
-本目录承载**需求(PRD)与第三方对接**的长期文档,与代码同仓库、同 PR 评审、同版本。
-
-## 文档体系与交接
-
-```
-docs/knowledge-base/requirements/
-  ├─ _templates/              PRD 模板
-  └─ <YYYYMMDD-功能名>/        一个功能一个目录,日期=该功能起始日   ──┐
-       ├─ PRD-001-<功能名>.md          产品需求文档                  │
-       ├─ PRD-001.gate.yaml            门禁状态(机器真相源)          │
-       ├─ PRD-001-REVIEW.md            门禁评审报告(人类可读)        │
-       └─ CHANGES-MAP.md               (多 change 时)功能项→change 映射 │
-                                                                    ├─→ /comate-gate (门禁+拆分)
-docs/knowledge-base/integrations/                                   │         ↓
-  第三方对接档案/索引 (跨需求长期存在)                              ──┘   comate changes
-```
-
-## PRD → comate 流程
-
-comate 采用**简化需求流**:只保留 **PRD**(产品需求文档),通过 `/comate-gate` 做两件事:
-
-1. **门禁**:审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零,禁止建任何 change。
-2. **拆分**:按依赖/整体性/独立性/规模判定该 PRD 变成 1 或 N 个 comate change(粒度由用户定),逐个交给 `/comate-open`。
-
-PRD 门禁状态钉在同级 `PRD-<三位序号>.gate.yaml`(机器真相源,含 `gate_status` / `score` / `blocking_open` / `prd_hash` / `spawned_changes`)。评审报告为 `PRD-<三位序号>-REVIEW.md`(人类可读,含问题台账)。PRD 通过门禁后被改会因哈希漂移自动失效(`stale`),需重跑 gate。
-
+# 知识库 (Knowledge Base)
+
+本目录承载**需求(PRD)与第三方对接**的长期文档,与代码同仓库、同 PR 评审、同版本。
+
+## 文档体系与交接
+
+```
+docs/knowledge-base/requirements/
+  ├─ _templates/              PRD 模板
+  └─ <YYYYMMDD-功能名>/        一个功能一个目录,日期=该功能起始日   ──┐
+       ├─ PRD-001-<功能名>.md          产品需求文档                  │
+       ├─ PRD-001.gate.yaml            门禁状态(机器真相源)          │
+       ├─ PRD-001-REVIEW.md            门禁评审报告(人类可读)        │
+       └─ CHANGES-MAP.md               (多 change 时)功能项→change 映射 │
+                                                                    ├─→ /comate-gate (门禁+拆分)
+docs/knowledge-base/integrations/                                   │         ↓
+  第三方对接档案/索引 (跨需求长期存在)                              ──┘   comate changes
+```
+
+## PRD → comate 流程
+
+comate 采用**简化需求流**:只保留 **PRD**(产品需求文档),通过 `/comate-gate` 做两件事:
+
+1. **门禁**:审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零,禁止建任何 change。
+2. **拆分**:按依赖/整体性/独立性/规模判定该 PRD 变成 1 或 N 个 comate change(粒度由用户定),逐个交给 `/comate-open`。
+
+PRD 门禁状态钉在同级 `PRD-<三位序号>.gate.yaml`(机器真相源,含 `gate_status` / `score` / `blocking_open` / `prd_hash` / `spawned_changes`)。评审报告为 `PRD-<三位序号>-REVIEW.md`(人类可读,含问题台账)。PRD 通过门禁后被改会因哈希漂移自动失效(`stale`),需重跑 gate。
+
 扇出的 comate change 内部用 proposal / design / tasks 承接 PRD 的功能项内容，PRD 直接作为 change 的源文档被 `sources track` 钉住。
-
+
 ## 命名约定
 
 - 功能目录：`<YYYYMMDD-功能名>/`
 - PRD：目录内 `PRD-<三位序号>-<功能名>.md`
 - gate 和评审报告：由脚本根据 PRD 路径自动生成，不手工命名。
-
-## 横向 (integrations/)
-
-- `integrations/` —— 第三方业务/接口对接档案与总索引,**跨多个需求长期存在**。
-- 单个 PRD 生命周期随功能上线收敛;本目录的内容长期维护,故独立放置。
-- PRD 的「第三方依赖」表应链接到 `integrations/<平台名>/README.md`。
-
-## 溯源与可追溯
-
-- PRD 顶部溯源块可选(若有更上游背景文档);没有上游时 PRD 是起点。
-- PRD 经门禁后扇出的 change 名记录在 `<PRD>.gate.yaml` 的 `spawned_changes` 字段,形成 PRD → change 的正向链。
-- 每个 change 的 `sources.manifest` 记录 PRD 路径与 sha256,形成 change → PRD 的反向链。
+
+## 横向 (integrations/)
+
+- `integrations/` —— 第三方业务/接口对接档案与总索引,**跨多个需求长期存在**。
+- 单个 PRD 生命周期随功能上线收敛;本目录的内容长期维护,故独立放置。
+- PRD 的「第三方依赖」表应链接到 `integrations/<平台名>/README.md`。
+
+## 溯源与可追溯
+
+- PRD 顶部溯源块可选(若有更上游背景文档);没有上游时 PRD 是起点。
+- PRD 经门禁后扇出的 change 名记录在 `<PRD>.gate.yaml` 的 `spawned_changes` 字段,形成 PRD → change 的正向链。
+- 每个 change 的 `sources.manifest` 记录 PRD 路径与 sha256,形成 change → PRD 的反向链。

package/skills/comate-gate/scaffold/docs/knowledge-base/integrations/_TEMPLATE/README.md

@@ -1,49 +1,49 @@
-# 第三方对接档案: <平台名>
-
-| 作者 | 更新时间 | 原文档地址 |
-|------|---------|-----------|
-| <建档/最近修改人,默认 git 用户名> | <YYYY-MM-DD,改动即更新> | <官方文档主 URL> |
-
-> 复制本目录,重命名为平台名,删除本行与所有 `<...>` 占位说明。
-> 本文件是「对接档案」——长期维护,不是官方文档副本。
-> 标题正下方的「作者/更新时间/原文档地址」三项**必填**:本档案是我方二开文档,须随时可追溯回官方原文。
-
-## 基本信息
-
-| 字段 | 内容 |
-|------|------|
-| 服务标识 | <目录名,如 oceanengine> |
-| 对接目的 | <为什么对接它,支撑哪个需求> |
-| 关联需求 | docs/knowledge-base/requirements/<YYYYMMDD-功能名>/PRD-001-<功能名>.md |
-| 关联变更 | openspec/changes/<变更名>/ |
-| 官方文档 | <URL> |
-| 我方负责人 | <name> |
-| 对方联系人 | <姓名/渠道,非必填> |
-| 接入状态 | 调研中 / 联调中 / 使用中 / 暂停使用 / 待下线 / 已下线 |
-| 最近校验 | <YYYY-MM-DD> |
-
-## 凭证与密钥位置(只写在哪,不写值)
-
-> ⚠️ 严禁把 token / secret / 私钥 写进本文件或任何 git 文件。
-
-| 凭证 | 存放位置 | 环境 |
-|------|---------|------|
-| AppKey/AppSecret | <如:K8s Secret xxx / 密钥系统路径> | 开发/生产 |
-
-## 接口清单(我方实际用到的)
-
-| 用途 | 方法/路径 | 限流/配额 | 备注 |
-|------|----------|----------|------|
-| <如 OAuth 换 token> | POST /xxx | <QPS/日配额> | <...> |
-
-详细字段摘录见 `api-snapshot.md`。
-
-## 失败与降级
-
-> PRD 门禁要求:凡有外部依赖必单列降级/失败场景。
-
-| 场景 | 表现 | 处理策略 |
-|------|------|----------|
-| 超时 | <...> | <重试/降级/告警> |
-| 未配置 | <...> | <...> |
-| 返回错误 | <...> | <...> |
+# 第三方对接档案: <平台名>
+
+| 作者 | 更新时间 | 原文档地址 |
+|------|---------|-----------|
+| <建档/最近修改人,默认 git 用户名> | <YYYY-MM-DD,改动即更新> | <官方文档主 URL> |
+
+> 复制本目录,重命名为平台名,删除本行与所有 `<...>` 占位说明。
+> 本文件是「对接档案」——长期维护,不是官方文档副本。
+> 标题正下方的「作者/更新时间/原文档地址」三项**必填**:本档案是我方二开文档,须随时可追溯回官方原文。
+
+## 基本信息
+
+| 字段 | 内容 |
+|------|------|
+| 服务标识 | <目录名,如 oceanengine> |
+| 对接目的 | <为什么对接它,支撑哪个需求> |
+| 关联需求 | docs/knowledge-base/requirements/<YYYYMMDD-功能名>/PRD-001-<功能名>.md |
+| 关联变更 | openspec/changes/<变更名>/ |
+| 官方文档 | <URL> |
+| 我方负责人 | <name> |
+| 对方联系人 | <姓名/渠道,非必填> |
+| 接入状态 | 调研中 / 联调中 / 使用中 / 暂停使用 / 待下线 / 已下线 |
+| 最近校验 | <YYYY-MM-DD> |
+
+## 凭证与密钥位置(只写在哪,不写值)
+
+> ⚠️ 严禁把 token / secret / 私钥 写进本文件或任何 git 文件。
+
+| 凭证 | 存放位置 | 环境 |
+|------|---------|------|
+| AppKey/AppSecret | <如:K8s Secret xxx / 密钥系统路径> | 开发/生产 |
+
+## 接口清单(我方实际用到的)
+
+| 用途 | 方法/路径 | 限流/配额 | 备注 |
+|------|----------|----------|------|
+| <如 OAuth 换 token> | POST /xxx | <QPS/日配额> | <...> |
+
+详细字段摘录见 `api-snapshot.md`。
+
+## 失败与降级
+
+> PRD 门禁要求:凡有外部依赖必单列降级/失败场景。
+
+| 场景 | 表现 | 处理策略 |
+|------|------|----------|
+| 超时 | <...> | <重试/降级/告警> |
+| 未配置 | <...> | <...> |
+| 返回错误 | <...> | <...> |

package/skills/comate-gate/scaffold/docs/knowledge-base/integrations/_TEMPLATE/api-snapshot.md

@@ -1,47 +1,47 @@
-# <平台名> 接口摘录 (API Snapshot)
-
-| 作者 | 更新时间 | 原文档地址 |
-|------|---------|-----------|
-| <建档/最近修改人,默认 git 用户名> | <YYYY-MM-DD,改动即更新> | <官方文档主 URL> |
-
-> 只摘录**我方实际用到**的接口与字段,不复制官方全文。
-> 标题正下方的「作者/更新时间/原文档地址」三项**必填**(本档案是我方二开文档,须可追溯回官方原文)。
-> 官方文档: <URL>
-> 抓取日期: <YYYY-MM-DD>  ← 每次对照官方更新时改这里
-
----
-
-## <接口1: 如 获取 access_token>
-
-**请求**
-```
-POST https://<host>/oauth/token
-Content-Type: application/json
-```
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| app_key | string | 是 | 见 README 凭证位置 |
-| grant_type | string | 是 | 固定 client_credentials |
-
-**响应**
-```json
-{
-  "access_token": "<string>",
-  "expires_in": 7200
-}
-```
-
-| 字段 | 说明 | 我方注意点 |
-|------|------|-----------|
-| expires_in | 有效期(秒) | ⚠️ 实测 2h,需提前刷新 |
-
-**错误码/异常**
-
-| code/status | 含义 | 我方处理 |
-|-------------|------|----------|
-| <...> | <...> | <重试/告警/提示用户/忽略> |
-
----
-
-## <接口2: ...>
+# <平台名> 接口摘录 (API Snapshot)
+
+| 作者 | 更新时间 | 原文档地址 |
+|------|---------|-----------|
+| <建档/最近修改人,默认 git 用户名> | <YYYY-MM-DD,改动即更新> | <官方文档主 URL> |
+
+> 只摘录**我方实际用到**的接口与字段,不复制官方全文。
+> 标题正下方的「作者/更新时间/原文档地址」三项**必填**(本档案是我方二开文档,须可追溯回官方原文)。
+> 官方文档: <URL>
+> 抓取日期: <YYYY-MM-DD>  ← 每次对照官方更新时改这里
+
+---
+
+## <接口1: 如 获取 access_token>
+
+**请求**
+```
+POST https://<host>/oauth/token
+Content-Type: application/json
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| app_key | string | 是 | 见 README 凭证位置 |
+| grant_type | string | 是 | 固定 client_credentials |
+
+**响应**
+```json
+{
+  "access_token": "<string>",
+  "expires_in": 7200
+}
+```
+
+| 字段 | 说明 | 我方注意点 |
+|------|------|-----------|
+| expires_in | 有效期(秒) | ⚠️ 实测 2h,需提前刷新 |
+
+**错误码/异常**
+
+| code/status | 含义 | 我方处理 |
+|-------------|------|----------|
+| <...> | <...> | <重试/告警/提示用户/忽略> |
+
+---
+
+## <接口2: ...>

package/skills/comate-gate/scaffold/docs/knowledge-base/requirements/_templates/PRD.md

@@ -1,97 +1,97 @@
-# PRD-<序号>-<功能名>: <产品标题>
-
+# PRD-<序号>-<功能名>: <产品标题>
+
 > 复制本文件到需求目录，按项目约定命名，删除本行与所有 `<...>` 占位说明。
 > PRD = 产品需求文档，回答「做成什么样」。本 PRD 由 `/comate-gate` 直接读取：先过质量门禁（审阅、评分、阻断检查），通过后按依赖和独立性拆成 1 或 N 个 comate change。
-
-| 字段 | 内容 |
-|------|------|
-| 产品编号 | PRD-001-<功能名> |
-| 产品负责人 | <PM name> |
-| 技术负责人 | <未知则留待补,不杜撰> |
-| 创建日期 | <YYYY-MM-DD> |
-| 优先级 | 高 / 中 / 低 |
-| 状态 | 设计中 / 评审中 / 已定稿 |
-| 关联迭代 | <如 2026-08 迭代,没有可删> |
-
-## 需求概述
-
-<一句话讲清这个产品/功能解决什么问题、给谁用。>
-
-## 用户与场景
-
-| 角色 | 场景 | 想要达成 |
-|------|------|----------|
-| <运营> | <每天看投放数据> | <无需手工导出即可日级复盘> |
-
-## 用户故事
-
-- 作为 <角色>,我希望 <能力>,以便 <价值>。
-
-## 产品方案 (What — 产品视角)
-
-<整体方案描述。可配流程图/示意。说明产品形态:是页面、后台任务、API、还是看板等。>
-
-### 核心流程
-
-1. <用户/系统从哪开始>
-2. <经过哪些关键步骤>
-3. <到哪结束,产出什么>
-
-### 功能清单
-
-> `/comate-gate` 据此清单判定拆分粒度:有依赖的功能项归同一 change,独立的可拆开。请标清优先级。
-
-| 功能 | 说明 | 优先级 (P0/P1/P2) |
-|------|------|------------------|
-| <功能A> | <做什么> | P0 |
-
-## 范围
-
-**做什么 (In Scope)**
-- <...>
-
-**不做什么 (Out of Scope)**
-- <明确边界,避免范围蔓延>
-
-## 交互 / 界面要点
-
-<关键页面、状态、空态/异常态。可链接设计稿。非视觉类(如纯后台任务)说明触发与产出形态。>
-
-## 第三方依赖
-
-<是否依赖外部平台/接口。若有,链接到对接档案,并说明失败/降级处理:>
-
-| 第三方 | 用途 | 风险 | 失败/降级处理 | 负责人 |
-|--------|------|------|--------------|--------|
-| <平台名> | <本产品中用它做什么> | <限流/权限/回调/稳定性等> | <超时/未配置/返回错误如何处理> | <name> |
-
-> 对接档案: docs/knowledge-base/integrations/<平台名>/README.md
-
-## 数据与来源
-
-> 门禁重点审查项:用到的数据必须交代来源(哪张表/哪个接口/哪方提供)、口径、单位、时间范围。
-
-- **数据来源**: <积分从哪来?余额存哪张表?哪个接口读?>
-- **成功指标**: <上线后用什么衡量产品是否成功,尽量可度量>
-
-## 边界与异常
-
-> 门禁重点审查项:极值、空值、并发、权限、异常路径、第三方失败是否覆盖。
-
-- <库存不足 / 并发冲突 / 重复提交 / 无权限 等如何处理>
-
-## 验收标准 (产品视角)
-
-> 门禁重点审查项:必须**可度量**,避免「体验流畅」这类不可验证的表述。
-
-- [ ] <可验证的产品行为,如「兑换成功率 ≥ 99.9%」「P99 响应 ≤ 500ms」>
-
-## 决策记录
-
-<为什么这样设计、放弃了哪些方案、权衡点。哪些能力不做、为什么不做。>
-
-## 变更历史
-
-| 日期 | 改动 | 人 |
-|------|------|----|
-| <YYYY-MM-DD> | 创建 | <name> |
+
+| 字段 | 内容 |
+|------|------|
+| 产品编号 | PRD-001-<功能名> |
+| 产品负责人 | <PM name> |
+| 技术负责人 | <未知则留待补,不杜撰> |
+| 创建日期 | <YYYY-MM-DD> |
+| 优先级 | 高 / 中 / 低 |
+| 状态 | 设计中 / 评审中 / 已定稿 |
+| 关联迭代 | <如 2026-08 迭代,没有可删> |
+
+## 需求概述
+
+<一句话讲清这个产品/功能解决什么问题、给谁用。>
+
+## 用户与场景
+
+| 角色 | 场景 | 想要达成 |
+|------|------|----------|
+| <运营> | <每天看投放数据> | <无需手工导出即可日级复盘> |
+
+## 用户故事
+
+- 作为 <角色>,我希望 <能力>,以便 <价值>。
+
+## 产品方案 (What — 产品视角)
+
+<整体方案描述。可配流程图/示意。说明产品形态:是页面、后台任务、API、还是看板等。>
+
+### 核心流程
+
+1. <用户/系统从哪开始>
+2. <经过哪些关键步骤>
+3. <到哪结束,产出什么>
+
+### 功能清单
+
+> `/comate-gate` 据此清单判定拆分粒度:有依赖的功能项归同一 change,独立的可拆开。请标清优先级。
+
+| 功能 | 说明 | 优先级 (P0/P1/P2) |
+|------|------|------------------|
+| <功能A> | <做什么> | P0 |
+
+## 范围
+
+**做什么 (In Scope)**
+- <...>
+
+**不做什么 (Out of Scope)**
+- <明确边界,避免范围蔓延>
+
+## 交互 / 界面要点
+
+<关键页面、状态、空态/异常态。可链接设计稿。非视觉类(如纯后台任务)说明触发与产出形态。>
+
+## 第三方依赖
+
+<是否依赖外部平台/接口。若有,链接到对接档案,并说明失败/降级处理:>
+
+| 第三方 | 用途 | 风险 | 失败/降级处理 | 负责人 |
+|--------|------|------|--------------|--------|
+| <平台名> | <本产品中用它做什么> | <限流/权限/回调/稳定性等> | <超时/未配置/返回错误如何处理> | <name> |
+
+> 对接档案: docs/knowledge-base/integrations/<平台名>/README.md
+
+## 数据与来源
+
+> 门禁重点审查项:用到的数据必须交代来源(哪张表/哪个接口/哪方提供)、口径、单位、时间范围。
+
+- **数据来源**: <积分从哪来?余额存哪张表?哪个接口读?>
+- **成功指标**: <上线后用什么衡量产品是否成功,尽量可度量>
+
+## 边界与异常
+
+> 门禁重点审查项:极值、空值、并发、权限、异常路径、第三方失败是否覆盖。
+
+- <库存不足 / 并发冲突 / 重复提交 / 无权限 等如何处理>
+
+## 验收标准 (产品视角)
+
+> 门禁重点审查项:必须**可度量**,避免「体验流畅」这类不可验证的表述。
+
+- [ ] <可验证的产品行为,如「兑换成功率 ≥ 99.9%」「P99 响应 ≤ 500ms」>
+
+## 决策记录
+
+<为什么这样设计、放弃了哪些方案、权衡点。哪些能力不做、为什么不做。>
+
+## 变更历史
+
+| 日期 | 改动 | 人 |
+|------|------|----|
+| <YYYY-MM-DD> | 创建 | <name> |