Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions .harness/skills/domain-init/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: >-
触发词:domain-init、领域初始化、生成领域规范、领域扫描
metadata:
author: "devkeel"
version: "2.0.2"
version: "2.1.0"
---

# Domain Init — 项目领域能力生成器
Expand All @@ -31,6 +31,7 @@ metadata:
- `references/project-index.md` — 参考项目索引(GitHub 地址 + 参考内容)
- `references/output-formats.md` — 产出格式规范 + 质量标准
- `references/domain-matrix.md` — 领域适用性矩阵(8 大领域 × 23 维度)
- `references/architecture-knowledge.md` — 选中 K1,或增强项涉及架构知识时,读取扫描与验收要求

## 何时使用

Expand Down Expand Up @@ -101,6 +102,7 @@ Phase 4: 收尾 → 配置更新 + 链接检查 + 生成报告

| ID | 维度 | 候选产出 | subAgent 职责 |
|----|------|------|--------------|
| K1 | 架构知识 | docs | 按 `references/architecture-knowledge.md` 扫描结构、组件归属、通信与关键流程 |
| R1 | 编码规范 | rule / docs | 扫描代码风格、格式化配置、lint 规则、导入习惯 |
| R4 | 测试策略 | rule / docs | 扫描测试框架、覆盖模式、测试文件组织、mock 策略 |
| R5 | 错误处理 | rule / docs | 扫描异常模式、日志使用、错误边界、重试策略 |
Expand All @@ -111,6 +113,8 @@ Phase 4: 收尾 → 配置更新 + 链接检查 + 生成报告
| R20 | 编辑纪律 | rule / docs | 基于 surgical changes 原则:只改相关代码 |
| A1 | 领域 Code Reviewer | agent | 基于以上扫描结果生成专属审查维度和输出规则 |

K1 面向所有领域,按实际代码触点裁剪;是否生成和调查深度仍由下述范围确认决定。

### 2.2 用户选择与优先级确认

**在扫描前,必须先让用户确认 baseline 范围和优先级。**
Expand Down Expand Up @@ -246,7 +250,7 @@ node .harness/skills/domain-init/scripts/sync-submodule-skills.mjs --prune #

### 4.4 生成报告

输出本次生成的完整清单(类型、文件、状态、参考项目),标记新增 vs 增强,建议后续完善方向,提醒用户 review 后 commit。
输出本次生成的完整清单(类型、文件、简述、状态、参考项目),标记新增 vs 增强,列出待确认事项、未覆盖范围与未验证行为,建议后续完善方向,并提醒用户 review 后 commit。

### 4.5 更新文档与 AGENTS 入口

Expand All @@ -258,7 +262,7 @@ node .harness/skills/domain-init/scripts/sync-submodule-skills.mjs --prune #
3. 更新 AGENTS 的文档链接与读取条件,规则和能力通过最小触发矩阵发现;不要求全量读取 docs。
4. 填充完成后删除该槽位成对的 `<!-- harness:user:... -->` / `<!-- /harness:user:... -->`
边界注释与已用完的占位提示,保留正文及相邻框架内容。未填槽位保留占位;已有正文不重加标记。
5. 核对相对链接、规则触发范围和事实来源。后续实施改变已验证的项目事实时,同步相关文档。
5. 按 `references/output-formats.md` 的质量标准核对产物及规则触发范围。后续实施改变已验证的项目事实时,同步相关文档。

| 用户槽位 | 内容 |
|----------|------|
Expand Down
52 changes: 52 additions & 0 deletions .harness/skills/domain-init/references/architecture-knowledge.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# 架构知识扫描与验收

选中 K1,或增强项涉及当前架构说明时使用。记录当前实现;待实施方案留在任务文档中。
只调查已确认的作用域和主题,按 `output-formats.md` 归属、引用与合并产物。

## 扫描顺序

1. **定位仓库与入口**:识别单仓、monorepo 或多仓;读取各目标仓库的 manifest、构建配置、
启动入口与已有文档。分别确认职责、技术栈、共享配置和依赖集成方式;根项目记录跨项目关系,
子项目记录自身实现,跨项目通过链接关联。
2. **追踪结构与依赖**:沿入口和代表性调用链核对模块、分层、组装位置与依赖方向。
区分源码调用、包/构建依赖与进程间通信;命名和目录只能提供线索,结论须核对代码与配置。
3. **追踪通信与流程**:从已确认范围内的关键入口追到结果及失败分支,核对跨边界调用、
消息或事件定义、状态变化及恢复处理。高优先项深入边界与例外,其余按已确认深度采样。
4. **映射已有文档**:将发现对应到已有主题和缺口,形成目标文件、依据及待确认事项,交回
Phase 2/3 review;跨仓调用链的发现不扩大对子项目的写入授权。

## 按需覆盖的内容

以下是内容检查项,不是固定章节或文件清单。已有文档能承接时直接更新;简单项目可合并,
没有触点的主题省略。DDD 仅在代码或已确认约定支持时展开。

| 主题 | 应回答的问题 | 可复用的文档位置示例 |
|------|--------------|----------------------|
| 项目与结构 | 项目做什么;各仓库/模块、入口、技术栈、分层、依赖方向与集成方式是什么 | project.md、architecture.md |
| 组件与归属 | 组件负责和不负责什么;边界依据是什么;新功能按什么判据归属 | architecture.md;内容较多时 components.md / modules.md |
| 通信与契约 | 谁调用谁;同步/异步、协议或机制、接口/消息定义、用途、所属模块和代码入口是什么 | architecture.md;按需拆分 communication-patterns.md / interfaces.md |
| 关键流程 | 从触发到结果经过哪些组件和状态;关键失败、超时、重试、取消或恢复在何处处理 | 现有业务专题;按需创建流程文档 |
| 开发与交付 | 在哪里运行构建、测试和发布;哪些配置或脚本定义环境、版本与依赖更新方式 | development.md、testing.md、已有发布文档 |

组件归属在存在多种落点时使用简短决策表,列出任务类型、所属组件与边界依据。
现有代码只能证明边界和依赖;历史划分理由遵循 Docs 的证据标记要求,不反推为已确认决定。

通信检查由实际触点触发,覆盖 HTTP/RPC、队列、IPC、CLI/SDK 调用、回调或事件。
接口清单优先链接已有协议、schema、路由或公开头文件;缺少导航时仅补充定位表,字段按机制裁剪
为方法/命令/路径/topic、用途、调用方与接收方、所属模块和定义位置,避免复制完整定义。
未发现的超时或恢复机制记为扫描范围内的缺口,不补写理想行为。

## 图表与导航

- 模块或跨仓关系难以用短文解释时,用 Mermaid flowchart/graph 表达职责与依赖方向;
跨组件交互复杂时用 sequenceDiagram,必要时补充状态图。简单关系用文字或表格。
- 图中参与者、调用方向和状态须与实现及正文一致。显示文本加引号;classDiagram 使用合法类
标识符,不将带 `::` 的命名空间直接用作类标识符。
- 专题之间用相对链接关联;文档索引注明用途和读取场景,AGENTS 只链接实际存在的文档。

## 完成检查

- 读者能找到入口、职责边界、依赖方向与相关代码,能判断新增功能的归属。
- 已选且有触点的通信与流程说明包含调用双方、关键状态和失败路径;无法追踪的边界已列明。
- 图表、正文和接口导航使用一致名称与方向,关键结论可定位到证据。
- 已覆盖主题能指向目标文档;未覆盖范围、推断、待确认事项和未验证行为进入报告。
3 changes: 3 additions & 0 deletions .harness/skills/domain-init/references/dimension-pool.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@

基于 Phase 1 识别的领域,**过滤掉不适用的维度**后,向用户展示可选增强项。
R-* 是扫描主题:执行约束进入 rules,背景、结构和示例进入 docs;不强制每个主题生成 rule。
选中 R2、R3、R9、S12 或 S13 且涉及当前架构知识时,读取
[架构知识扫描与验收](architecture-knowledge.md)。已选择 K1 时复用本轮扫描和已有产物,仅补选中范围的缺口。
通信与流程按实际触点调查,包含系统/C++ 的 IPC、回调和事件,不受 R9 的展示过滤限制。

## 规则与项目知识增强池

Expand Down
6 changes: 6 additions & 0 deletions .harness/skills/domain-init/references/output-formats.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,10 @@ OpenSpec 内容保留在主仓库 `openspec/`;项目文档引用相关规范
标题说明主题;按实际需要记录适用范围、当前事实、来源和相关入口,不强制章节数量。
命令注明运行目录并链接对应 scripts;详细示例注明用途,不把示意代码当作当前实现。

关键结论引用代码或配置的相对路径与符号,必要时给出起始行;已确认约定链接其记录。
缺少证据的历史设计理由标为「推测」或「待确认」,改进建议与当前事实分开。
只做静态扫描时明确证据边界,不将配置声明或调用关系写成已运行验证的行为。

- `docs/README.md` 可作为按任务组织的索引,已有索引则复用。
- 文件名沿用项目惯例;项目概览、架构、开发与测试说明按需创建,不生成空目录和占位文档。
- AGENTS 的 `project` 槽位统一维护项目知识入口;rules 按需引用相关说明。只添加已存在文件
Expand Down Expand Up @@ -94,6 +98,8 @@ model: sonnet
| 内容归属 | 约束与知识分开,低频硬约束不丢失 |
| 文档引用 | 链接存在、读取条件明确、同主题复用 |
| 代码依据 | 约定必须能在项目代码中找到出处 |
| 术语一致 | 模块、组件、接口和消息名称在正文、图表与引用中一致 |
| 架构知识 | 涉及架构的产物按 [架构知识扫描与验收](architecture-knowledge.md) 检查 |
| Skill 完整性 | 必须有「何时使用」和「Hard Rules」 |
| Agent 完整性 | 必须有「审查维度」和「输出规则」 |
| 禁止理想化 | 不输出与项目实际不符的规范 |
Expand Down
2 changes: 1 addition & 1 deletion .harness/versions.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ skills:
openspec-onboard: "2.4"
openspec-sync-specs: "2.2"
openspec-verify-change: "3.4"
domain-init: "2.0.2"
domain-init: "2.1.0"
verify-init: "2.0.1"
ui-fidelity-playbook: "1.0.3"
rules: {}
Expand Down
41 changes: 39 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,10 +94,10 @@ Lite / Full 使用 OpenSpec 保存共同设计和任务过程。常用入口是

| 命令 | 用途 | 常用选项 |
|------|------|----------|
| `devkeel init` | 初始化协作资产和平台入口 | `--name`、`--targets`、`-y`、`--force` |
| `devkeel init` | 初始化协作资产和平台入口 | `--name`、`--targets`、`-y`、`--force`、`--template-package`、`--template-registry` |
| `devkeel doctor` | 检查协作资产 | `--fix` |
| `devkeel sync` | 同步平台入口 | `--targets`、`--force` |
| `devkeel update` | 更新当前项目的模板资产 | `--dry-run`、`--force`、`--beta`、`--template-version` |
| `devkeel update` | 更新当前项目的模板资产 | `--dry-run`、`--force`、`--beta`、`--template-version`、`--template-package`、`--template-registry` |
| `devkeel evidence` | 收集 OpenSpec change 的实现证据 | `--change <name>`、`--json`、`--write-base` |
| `devkeel openspec <命令>` | 调用内置 OpenSpec CLI | 如 `list`、`status`、`validate` |
| `devkeel -V` | 查询 CLI 与模板的发布渠道版本 | 可加 `--beta` |
Expand All @@ -118,6 +118,43 @@ devkeel update
`devkeel update` 不升级全局 CLI。选择“全部更新”或使用 `--force` 会覆盖受管组件中的本地修改;
退役的受管 Skill 目录及其中的自定义内容也可能被删除。更新前先查看 `--dry-run` 结果。

### 使用自定义模板源

`init` 和 `update` 支持指定兼容 DevKeel 目录布局的 npm 模板包:

```bash
devkeel init --template-package @example/devkeel-templates --template-registry https://npm.example.com/
# 已初始化项目可通过 update 切换来源,建议先预览
devkeel update --template-package @example/devkeel-templates --template-registry https://npm.example.com/ --dry-run
```

来源配置分两级,使用相同的 JSON 格式:

- 用户级:`~/.harness/template-source.json`,手动配置一次,供所有项目继承。
- 项目级:`.harness/template-source.json`,覆盖用户级配置,可随项目提交。

例如在用户级文件中配置:

```json
{
"packageName": "@example/devkeel-templates",
"registry": "https://npm.example.com/"
}
```

各字段优先级为:命令行参数 → 项目级配置 → 用户级配置 → 默认值。两个字段均可单独配置。
未配置项目级来源的项目直接继承用户级来源,不会自动生成项目级文件。
显式传入来源参数并成功执行后,参数会保存为项目级覆盖;继承的字段不会被固定下来。
删除项目级文件即可恢复继承用户级来源,后续直接运行 `devkeel update`。
默认包为 `devkeel-templates`;未指定 registry 时,遵循 npm 的 scope registry 或普通 registry
配置,且不会把这个解析结果固定到来源文件。认证由项目或用户 `.npmrc` 提供,来源文件不保存凭据。
`-V` 与 `doctor` 更新提示也使用相同的来源优先级;CLI 自身的发布查询保持独立。

缓存按 registry、包名、版本隔离。切换来源时,即使组件版本号相同也会重新检查,仍沿用原有
覆盖确认流程;`--force` 会覆盖本地修改。中断或跳过组件时不保存新来源,需带相同参数重试。
`--dry-run` 可下载缓存,但不修改配置或项目资产。拉取失败不会回退到公共模板。
版本与渠道参数只影响本次更新,不会持久化。当前仅支持 npm 包,不支持本地目录或 Git URL。

## 开发与文档

从[项目文档索引](docs/README.md)进入开发、测试与构建说明;源码与问题反馈见
Expand Down
7 changes: 7 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,13 @@
平台由现有目录和入口文件识别,CLI 不读取或生成 `.harness/config.yml`。
[update.ts](../src/lib/update.ts)维护资产更新和兼容迁移。

[template-source.ts](../src/lib/template-source.ts)统一解析模板包及 npm registry:命令行参数覆盖
项目 `.harness/template-source.json`,项目配置覆盖用户 `~/.harness/template-source.json`,缺省时使用 `devkeel-templates` 和 npm 配置。来源文件仅保存包名与
显式 registry,不保存认证信息。普通项目继承用户配置;仅显式参数或已有项目配置落盘为项目覆盖。`.harness/versions.yml` 的 `templateSource` 保存已完成同步的
来源指纹;换源过程中为 `pending`,确保失败或部分更新后重试仍检查同版本组件。
[templates-cache.ts](../src/lib/templates-cache.ts)按来源指纹及版本隔离下载缓存,npm 在项目目录
运行以沿用 `.npmrc`;下载、版本输出和更新提示使用同一来源解析。

约束见 [架构规则](../.harness/rules/architecture-constraints.md)。例如 templates 调用版本读取、
detect 复用模板目录检查能力;模块依赖应保持无环。模板渲染使用 `{{VAR}}` 替换,具体实现以
[renderTemplate](../src/lib/templates.ts)为准。
Expand Down
2 changes: 1 addition & 1 deletion openspec/specs/domain-templates/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@

- **WHEN** 对比领域模板与主仓库模板
- **THEN** 领域模板 SHALL 不复制 Direct/Lite/Full、Brainstorming 或 OpenSpec 的主仓库编排算法
- **AND** 模板 SHALL 明确代码与验证留在子仓库、OpenSpec 和知识产出归属主仓库
- **AND** 模板 SHALL 明确代码、验证与项目知识留在所属子仓库,项目知识写入其 `docs/`,OpenSpec 由主仓库协调

#### Scenario: Domain AGENTS.md is safe as a standalone entry

Expand Down
Loading