trigrams-toolkit 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- trigrams_toolkit/__init__.py +1 -0
- trigrams_toolkit/handbook/__init__.py +6 -0
- trigrams_toolkit/handbook/cli.py +122 -0
- trigrams_toolkit/handbook/guide_headers.py +43 -0
- trigrams_toolkit/handbook/guides.py +141 -0
- trigrams_toolkit/handbook/location.py +79 -0
- trigrams_toolkit/handbook/model.py +4 -0
- trigrams_toolkit/handbook/package.py +165 -0
- trigrams_toolkit/handbook/principle_import.py +101 -0
- trigrams_toolkit/handbook/project_resources.py +80 -0
- trigrams_toolkit/handbook/skill_sources.py +59 -0
- trigrams_toolkit/handbook/source_catalog.py +55 -0
- trigrams_toolkit/handbook/sources.py +16 -0
- trigrams_toolkit/installation/__init__.py +0 -0
- trigrams_toolkit/installation/archive_project.py +50 -0
- trigrams_toolkit/installation/global_skills.py +45 -0
- trigrams_toolkit/installation/harness_install.py +89 -0
- trigrams_toolkit/installation/installation_candidate.py +135 -0
- trigrams_toolkit/installation/installation_help.py +49 -0
- trigrams_toolkit/installation/installation_materials.py +73 -0
- trigrams_toolkit/installation/installation_service.py +14 -0
- trigrams_toolkit/installation/installation_sources.py +34 -0
- trigrams_toolkit/installation/operation_files.py +94 -0
- trigrams_toolkit/installation/operation_runtime.py +144 -0
- trigrams_toolkit/installation/package_metadata.py +48 -0
- trigrams_toolkit/plan/__init__.py +5 -0
- trigrams_toolkit/plan/cli.py +136 -0
- trigrams_toolkit/plan/definitions.py +131 -0
- trigrams_toolkit/plan/model.py +61 -0
- trigrams_toolkit/plan/scheduling.py +126 -0
- trigrams_toolkit/plan/service.py +139 -0
- trigrams_toolkit/plan/state.py +146 -0
- trigrams_toolkit/project_context/__init__.py +16 -0
- trigrams_toolkit/project_context/paths.py +36 -0
- trigrams_toolkit/py.typed +0 -0
- trigrams_toolkit/resources/__init__.py +35 -0
- trigrams_toolkit/resources/adapters/claude/README.md +7 -0
- trigrams_toolkit/resources/adapters/claude/evaluator.md +7 -0
- trigrams_toolkit/resources/adapters/claude/task_developer.md +7 -0
- trigrams_toolkit/resources/adapters/codex/README.md +9 -0
- trigrams_toolkit/resources/adapters/codex/evaluator.toml +6 -0
- trigrams_toolkit/resources/adapters/codex/task_developer.toml +6 -0
- trigrams_toolkit/resources/adapters/pi-web/evaluator.md +7 -0
- trigrams_toolkit/resources/adapters/pi-web/task_developer.md +7 -0
- trigrams_toolkit/resources/handbook/PROTOCOL.md +82 -0
- trigrams_toolkit/resources/handbook/README.md +45 -0
- trigrams_toolkit/resources/handbook/commands.json +31 -0
- trigrams_toolkit/resources/handbook/guides.schema.json +253 -0
- trigrams_toolkit/resources/installation/PROTOCOL.md +35 -0
- trigrams_toolkit/resources/installation/cli.schema.json +89 -0
- trigrams_toolkit/resources/installation/commands.json +23 -0
- trigrams_toolkit/resources/installation/examples/install-apply-input.json +48 -0
- trigrams_toolkit/resources/installation/examples/install-preview-input.json +7 -0
- trigrams_toolkit/resources/installation/examples/installation.json +20 -0
- trigrams_toolkit/resources/installation/global-skills.json +6 -0
- trigrams_toolkit/resources/installation/installation.schema.json +295 -0
- trigrams_toolkit/resources/plan/PROTOCOL.md +89 -0
- trigrams_toolkit/resources/plan/README.md +61 -0
- trigrams_toolkit/resources/plan/commands.json +36 -0
- trigrams_toolkit/resources/plan/plan.schema.json +192 -0
- trigrams_toolkit/resources/shared/GLOBAL-TOOLS.md +31 -0
- trigrams_toolkit/resources/shared/common.schema.json +234 -0
- trigrams_toolkit/resources/state/PROTOCOL.md +85 -0
- trigrams_toolkit/resources/state/README.md +88 -0
- trigrams_toolkit/resources/state/cli.schema.json +326 -0
- trigrams_toolkit/resources/state/commands.json +55 -0
- trigrams_toolkit/resources/state/core-types.json +5 -0
- trigrams_toolkit/resources/state/help.json +86 -0
- trigrams_toolkit/resources/state/sources.schema.json +89 -0
- trigrams_toolkit/resources/state/state.schema.json +200 -0
- trigrams_toolkit/shared/__init__.py +1 -0
- trigrams_toolkit/shared/cli_help.py +195 -0
- trigrams_toolkit/shared/errors.py +29 -0
- trigrams_toolkit/shared/files.py +66 -0
- trigrams_toolkit/shared/locking.py +49 -0
- trigrams_toolkit/shared/paths.py +89 -0
- trigrams_toolkit/shared/process_lock.py +77 -0
- trigrams_toolkit/shared/schema.py +60 -0
- trigrams_toolkit/shared/serialization.py +84 -0
- trigrams_toolkit/shared/skill_installations.py +66 -0
- trigrams_toolkit/shared/state_json.py +45 -0
- trigrams_toolkit/state/__init__.py +4 -0
- trigrams_toolkit/state/arguments.py +68 -0
- trigrams_toolkit/state/cli.py +37 -0
- trigrams_toolkit/state/frontmatter.py +176 -0
- trigrams_toolkit/state/help.py +25 -0
- trigrams_toolkit/state/identity.py +123 -0
- trigrams_toolkit/state/location.py +59 -0
- trigrams_toolkit/state/model.py +76 -0
- trigrams_toolkit/state/providers.py +77 -0
- trigrams_toolkit/state/registration.py +82 -0
- trigrams_toolkit/state/relations.py +105 -0
- trigrams_toolkit/state/service.py +90 -0
- trigrams_toolkit/state/store.py +33 -0
- trigrams_toolkit/state/views.py +64 -0
- trigrams_toolkit/version.py +6 -0
- trigrams_toolkit-0.1.0.dist-info/METADATA +69 -0
- trigrams_toolkit-0.1.0.dist-info/RECORD +103 -0
- trigrams_toolkit-0.1.0.dist-info/WHEEL +5 -0
- trigrams_toolkit-0.1.0.dist-info/entry_points.txt +5 -0
- trigrams_toolkit-0.1.0.dist-info/licenses/LICENSE +21 -0
- trigrams_toolkit-0.1.0.dist-info/licenses/THIRD_PARTY_NOTICES.md +18 -0
- trigrams_toolkit-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""Package-owned contracts; extracted files live until process shutdown."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import atexit
|
|
5
|
+
from contextlib import ExitStack
|
|
6
|
+
from functools import cache
|
|
7
|
+
from importlib.resources import as_file, files
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
_files = ExitStack()
|
|
11
|
+
atexit.register(_files.close)
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
@cache
|
|
15
|
+
def resource_path(name: str) -> Path:
|
|
16
|
+
"""Keep as_file's context alive for consumers retaining schema paths."""
|
|
17
|
+
return _files.enter_context(as_file(files(__package__).joinpath(name)))
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@cache
|
|
21
|
+
def schema_paths() -> tuple[Path, ...]:
|
|
22
|
+
return tuple(resource_path(f"{component}/{entry.name}")
|
|
23
|
+
for component in ("plan", "handbook", "state", "installation", "shared")
|
|
24
|
+
for entry in sorted(files(__package__).joinpath(component).iterdir(), key=lambda p: p.name)
|
|
25
|
+
if entry.name.endswith(".schema.json"))
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def adapter_files(platform: str) -> dict[str, bytes]:
|
|
29
|
+
targets = {"codex": ".codex/agents", "claude": ".claude/agents", "pi-web": ".pi/agents"}
|
|
30
|
+
root = files(__package__).joinpath("adapters", platform)
|
|
31
|
+
return {f"{targets[platform]}/{entry.name}": entry.read_bytes()
|
|
32
|
+
for entry in root.iterdir() if entry.is_file()}
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
__all__ = ["resource_path", "schema_paths", "adapter_files"]
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Claude Adapter
|
|
2
|
+
|
|
3
|
+
core 项目安装按所选平台将两个角色入口复制到项目 `.claude/agents/`,分别调用 `execute-task` 与 `delivery-review` Skill,无需启用领域扩展。
|
|
4
|
+
|
|
5
|
+
`src/trigrams_toolkit/resources/adapters/claude/` 是配置唯一来源,安装器按已确认预览将角色入口复制到 `.claude/agents/`。公共 CLI 与 core Skill 分别由统一 Python 包(`uv tool install`)和 Vercel skills 全局安装,项目扩展 Skill 由 Vercel skills 安装至项目(Claude Code 使用 `.claude/skills/`,兼容与 `.agents/skills/` 同树复用);项目不预装 Plan 工具。全局安装与增补方法向 `toolkit-steward` 查询,首次接入方法通过 `handbook load core:workbook:initialize` 加载。
|
|
6
|
+
|
|
7
|
+
角色默认 `model: inherit`,权限沿用宿主。新建角色后,在新会话核对实际发现。项目 CLAUDE.md 引用已装配的 AGENTS.md,保留项目原有 Claude 规则。
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Codex Adapter
|
|
2
|
+
|
|
3
|
+
core 项目安装按所选平台将两个角色入口复制到项目 `.codex/agents/`,分别调用 `execute-task` 与 `delivery-review` Skill,无需启用领域扩展。
|
|
4
|
+
|
|
5
|
+
`src/trigrams_toolkit/resources/adapters/codex/` 是配置唯一来源,安装器按已确认预览将角色入口复制到 `.codex/agents/`。公共 CLI 与 core Skill 分别由统一 Python 包(`uv tool install`)和 Vercel skills 全局安装,项目扩展 Skill 与资源快照分别由 Vercel skills 与 `harness-install` 装配;项目不预装 Plan 工具。全局安装与增补方法向 `toolkit-steward` 查询,首次接入方法通过 `handbook load core:workbook:initialize` 加载。
|
|
6
|
+
|
|
7
|
+
默认沿用会话模型与推理设置;项目固定模型时,在平台入口保存实际可用配置。角色使用 workspace-write,工作边界由 Task 与 Skill 确定。在新会话核对实际角色发现,当前会话不会自动刷新。
|
|
8
|
+
|
|
9
|
+
当前安装中断时,读取 initialize workbook 的安装说明并按其中的回退方法恢复。配套材料相对 `handbook load` 返回的 `entryPath` 定位。
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Handbook
|
|
2
|
+
|
|
3
|
+
`handbook` 提供 workbook 与 principle 的目录、正文加载和声明校验,并将已审定原则草稿写入项目正式库。Skill 使用宿主发现入口。
|
|
4
|
+
|
|
5
|
+
## 命令
|
|
6
|
+
|
|
7
|
+
| 命令 | 参数与结果 |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| `scopes` | 可选 `--kind workbook\|principle`。`scopes[]` 返回当前项目可见资料的目录分类,去重并排序。 |
|
|
10
|
+
| `list` | 可选 `--kind workbook\|principle` 和可重复的 `--scope SCOPE`。多个分类取并集;省略时不按分类筛选。`resources[]` 每项严格只有 `resourceId` 和 `description`,两类资源一致。 |
|
|
11
|
+
| `load ID [ID ...]` | 接受一个或多个完整 ID 或唯一短名,共用一次项目解析与资料目录。返回入口及 workbook 递归 includes 的正文与来源,批量响应见下文。 |
|
|
12
|
+
| `validate` | 校验 principle 两级布局、入口头信息、身份和 includes 引用,返回 checkedSources 与 resourceIds。 |
|
|
13
|
+
| `import-principle FILE --scope SCOPE --name NAME [--replace]` | 将已审定草稿入库。返回 `resourceId`、绝对 `entryPath` 和 `operation`(`created` 或 `updated`)。 |
|
|
14
|
+
|
|
15
|
+
scopes、list、load 和 validate 从目标项目根运行,读取该根的项目资料和全局 core Skill 的资料目录。principle 的 scope 取 principles 下一级目录的完整名称,`programming` 与 `programming-design` 平级且精确匹配。workbook 的 scope 取入口父目录名中第一个连字符前的部分,无连字符时取完整目录名。workbook 的 includes 可跨分类加载。
|
|
16
|
+
|
|
17
|
+
可在任意目录用 `-h` 或 `--help` 查询参数,用 `-v` 或 `--version` 查看版本。帮助为纯文本,业务结果为精简 JSON。
|
|
18
|
+
|
|
19
|
+
### 原则入库
|
|
20
|
+
|
|
21
|
+
`import-principle` 从目标项目根运行。`FILE` 从当前根解析,也接受已审定草稿的绝对路径。输出始终位于当前根。scope 和 name 使用现有英文小写连字符 token 规则。
|
|
22
|
+
|
|
23
|
+
正式入口为 `docs/knowledge/principles/<scope>/<name>/PRINCIPLE.md`,身份为 `project:principle:<scope>/<name>`。默认只创建新目标,已有目标返回冲突。`--replace` 只更新已有文件,目标缺失时报错。源文件与目标指向同一文件时拒绝入库。
|
|
24
|
+
|
|
25
|
+
输入接受任意文件名,按 principle schema 校验 YAML 头,正文应为非空 UTF-8 文本。头信息只接受 description,不增加审批、scope 或 name 字段。CLI 保留已审定文件的字节和源草稿,不改写语义,也不搬运附件。正文及目标身份的用户审定、正式引用和附件位置由调用工作流确认。
|
|
26
|
+
|
|
27
|
+
入库先校验输入、目标和已有项目声明,再写入声明与正文,最后用既有项目来源及资料目录验证正式身份可发现。成功响应为 `{"ok": true, "resourceId": "project:principle:<scope>/<name>", "entryPath": "<绝对路径>", "operation": "created"}`,替换时 operation 为 updated,退出码为 0。
|
|
28
|
+
|
|
29
|
+
### 项目资源声明
|
|
30
|
+
|
|
31
|
+
handbook 内部模块统一创建、合并和校验 `docs/resources.json`。调用方提供当前项目根及相对 docs 的资源根,原则入库请求 `knowledge/principles`。
|
|
32
|
+
|
|
33
|
+
缺少声明时,模块创建 schemaVersion 为 1、source 为 project、version 为 1.0.0、install 为空数组的声明文件,resourceRoots 包含请求的资源根。已有声明按 resourceManifest schema 和既有路径规则校验,保留有效字段、版本、安装声明及资源根,再补充缺项并去重。已有父级根覆盖请求路径时,不新增重叠根。请求的父级根会覆盖既有子级根时,预检返回 resource_conflict,保留既有声明;调用方先明确整理声明再重试。声明未变化时不写文件。有效自定义根保留,原则仍写入标准路径。
|
|
34
|
+
|
|
35
|
+
模块准备阶段不创建目录或文件。格式损坏、source 非 project、非法资源根或越界路径在写入前报错,并保留原声明。模块只维护通用资源声明,不处理原则正文与身份。
|
|
36
|
+
|
|
37
|
+
### 入库错误与恢复
|
|
38
|
+
|
|
39
|
+
失败响应沿用 `ok: false`、`error.code` 和 `error.message`,退出码为 1。有定位信息时返回 `error.conflicts`。
|
|
40
|
+
|
|
41
|
+
| code | 入库条件 |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `invalid_arguments` | 非法 scope/name、源文件与目标相同,或参数组合无效。 |
|
|
44
|
+
| `invalid_reference` | 源文件缺失或不是文件、替换目标缺失,或资源来源无法读取。 |
|
|
45
|
+
| `invalid_schema` | 草稿头信息或正文格式无效、Package 不符合 schema。 |
|
|
46
|
+
| `invalid_json` | Package JSON 损坏或包含重复键。 |
|
|
47
|
+
| `identity_conflict` | 已有清单的 source 不是 project。 |
|
|
48
|
+
| `path_outside_root` | 声明、资源根或正式目标越过项目路径边界,或路径组成无效。 |
|
|
49
|
+
| `resource_conflict` | 创建目标已存在、既有资源根彼此重叠、请求资源根与既有子级根重叠,或发现链遇到重复身份、重复物理入口。 |
|
|
50
|
+
| `io_error` | 读取、目录创建或文件发布时发生普通 I/O 错误。 |
|
|
51
|
+
|
|
52
|
+
输入、声明与目标冲突在修改前返回。文件分别复用既有原子发布能力;声明与正文不组成跨文件事务。先写声明,再写正文。普通 I/O 失败和写入后的发现失败保留已经发布的结果,不报告成功,也不自动回退已发布文件。
|
|
53
|
+
|
|
54
|
+
写入阶段失败时,`error.current` 返回绝对 `packagePath`、`entryPath`,以及 `packageWritten`、`entryWritten`。标记为 true 表示已确认该文件包含本次待写内容;false 表示未发布该文件;无法确认时为 null。声明无需变更时,packageWritten 为 false。仅调用模块时,错误包含该模块负责的 packagePath 和 packageWritten。错误码保留实际失败分类。
|
|
55
|
+
|
|
56
|
+
恢复时先核对 error.current 指向的文件。正文未发布时,保留草稿,修复失败原因后重试原创建或替换操作。正文已发布或状态无法确认时,先核对正文与声明,再决定是否用 `--replace` 重试或修复发现错误。未确认当前结果前,不把失败当作未写入。
|
|
57
|
+
|
|
58
|
+
### 批量加载与错误
|
|
59
|
+
|
|
60
|
+
成功响应包含 `ok: true`、`selectedIds[]` 和 `resources[]`。`selectedIds` 保存解析后的完整入口 ID,按输入顺序去重。恰好传入一个 ID 时,响应还保留原 `selected` 字符串;传入多个参数时省略该字段,即使参数指向同一入口。
|
|
61
|
+
|
|
62
|
+
`resources` 按完整 ID 全局去重,保留首次遍历顺序;workbook 的依赖先于引用者返回。重复入口、短名与完整 ID 指向同一入口、多根共享依赖均只读取并输出一份正文。每项包含 `resourceId`、`kind`、`name`、`description`、`source`、`entryPath` 与 `content`;workbook 有非空 includes 时保留 `includes`。principle 的 `name` 取二级目录名。
|
|
63
|
+
|
|
64
|
+
任一入口缺失或歧义、格式非法或 includes 无效时,整次响应为 `ok: false`,退出码为 1,不返回部分成功正文。`error.code` 与 `error.message` 保留原分类及定位信息。短名歧义返回 `resource_conflict`,消息标明出错输入,`error.conflicts[]` 按完整 ID 排序给出全部候选,可直接用于下一次加载。有其他冲突定位信息时,同一字段返回原定位对象。正文中的普通引用按条件读取。
|
|
65
|
+
|
|
66
|
+
## 作者格式
|
|
67
|
+
|
|
68
|
+
principle 使用 `principles/<scope>/<principle>/PRINCIPLE.md`,相对于来源内的 principles 根固定两级目录。scope 和 principle 使用英文小写连字符名称;scope 不按连字符分层。资源来源与目录派生 `<source>:principle:<scope>/<principle>`,YAML 头只接受 `description`。`includes` 即使为空也在目录发现阶段返回 `invalid_schema`。改动 scope 或原则目录名后同步当前身份与路径引用;中文标题和 description 不影响身份。
|
|
69
|
+
|
|
70
|
+
workbook 的入口目录仍为 `<scope>` 或 `<scope>-<topic>`。`WORKBOOK.md` 的 YAML 头包含 `name`、`description` 和按需 `includes`;已被引用的 `resourceId` 保留,省略时使用 `<source>:workbook:<目录名>`。workbook 可递归包含 workbook 与 principle;principle 为叶子,单条加载只返回自身。
|
|
71
|
+
|
|
72
|
+
完整 ID 精确加载;principle 短名为 `scope/principle`,workbook 短名为 ID 最后一段,均只在当前目录中唯一时可用。重复身份、短名歧义、缺失 includes 和 workbook 依赖环返回错误。校验不限制正文篇幅。
|
|
73
|
+
|
|
74
|
+
入口类型取自文件名。正文头与资源清单的结构由 `guides.schema.json` 定义。正文头只接受 schema 声明的键。
|
|
75
|
+
|
|
76
|
+
## 资源清单与安装
|
|
77
|
+
|
|
78
|
+
core 从所选 agent 的全局 `principles` 和 `workbook` 各自读取资料。所有命令支持 `--agent`,省略时沿用项目安装记录或默认 `codex`。core 源码的 `skills/resources.json` 用于仓库校验。
|
|
79
|
+
|
|
80
|
+
扩展声明在 `.agents/extensions/<extension>/extension.json`,保存扩展名、版本、资源根、安装映射及可选的成果和关系类型。handbook 按项目安装记录发现受管资料,保留 workbook 与 principle 的稳定身份和相对引用。上游 Skill 更新后,通过 [harness-install](../installation/PROTOCOL.md) 显式更新项目快照。
|
|
81
|
+
|
|
82
|
+
项目自有资料由 `docs/resources.json` 声明,其路径与版本由项目维护。
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Handbook
|
|
2
|
+
|
|
3
|
+
handbook 提供 workbook 与 principle 的发现、加载和校验,并将已审定原则草稿写入项目正式库。完整契约见 [PROTOCOL.md](PROTOCOL.md)。
|
|
4
|
+
|
|
5
|
+
| 命令 | 返回与用途 |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| `scopes [--kind workbook\|principle]` | 返回当前项目可用 scope,去重并排序 |
|
|
8
|
+
| `list [--kind workbook\|principle] [--scope SCOPE]` | 每项只有 resourceId、description;重复 scope 取并集,省略时返回全部 |
|
|
9
|
+
| `load ID [ID ...]` | 一次读取多个入口,返回全局去重的正文、名称、来源、路径及 workbook 递归依赖 |
|
|
10
|
+
| `validate` | 校验布局、头信息、身份和 includes;返回 checkedSources 与 resourceIds |
|
|
11
|
+
| `import-principle FILE --scope SCOPE --name NAME [--replace]` | 写入已审定草稿,返回 resourceId、绝对 entryPath 和 operation(created 或 updated) |
|
|
12
|
+
|
|
13
|
+
```powershell
|
|
14
|
+
handbook scopes --kind principle
|
|
15
|
+
handbook list --kind principle --scope programming-design-architecture
|
|
16
|
+
handbook load core:principle:programming-design-architecture/separate-business-decisions-from-external-details
|
|
17
|
+
handbook validate
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
principle 使用 `principles/<scope>/<principle>/PRINCIPLE.md`。一级目录完整名称是 scope,二级英文小写连字符目录是原则名称。例如 programming-design-architecture 与 programming 是两个平级 scope,筛选精确匹配。ID 派生为 `<source>:principle:<scope>/<principle>`;唯一时可用 `scope/principle` 短名。
|
|
21
|
+
|
|
22
|
+
```yaml
|
|
23
|
+
---
|
|
24
|
+
description: 划分表现渲染、外部交互、编排逻辑与业务数据决策职责边界时使用(layer.policy-detail-split)。
|
|
25
|
+
---
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
principle 头信息只接受 description,带 includes(包括空数组)返回 invalid_schema。名称和身份从目录取得,改目录后同步当前引用。单条原则只加载自身,长正文和附件仍可使用;正文内的其他资料按条件读取。
|
|
29
|
+
|
|
30
|
+
workbook 沿用 `<scope>` 或 `<scope>-<topic>` 目录;scope 取第一个连字符前的部分。其 YAML 头保留 name、description、可选 resourceId 与 includes,省略 ID 时由来源、workbook 和目录名派生。目录改名时保留已被引用的显式 ID。includes 可跨 scope 递归包含 workbook 与 principle,principle 为叶子。
|
|
31
|
+
|
|
32
|
+
业务命令从目标项目根运行,输出 JSON,成功退出码为 0。检查 ok 后使用结果。批量中任一入口失败时整次失败,不输出部分正文。短名歧义返回可直接重试的完整候选 ID。可在任意目录用 `-h` 或 `--help` 查询参数,用 `-v` 或 `--version` 查看工具包版本。
|
|
33
|
+
|
|
34
|
+
资料来自目标 agent 的全局 `principles`、`workbook`,以及已登记的项目扩展快照与 `docs/resources.json`。用 `--agent` 指定全局 Skill 的宿主,省略时取安装记录或默认 `codex`。资源清单、来源边界和安装说明见协议的“资源清单与安装”。
|
|
35
|
+
|
|
36
|
+
原则入库前,先审定草稿正文、scope 和 name。项目原则草稿由 `principle-maintenance` 管理;CLI 接受任意位置及文件名。草稿采用上面的 description 头,正文为非空 UTF-8 文本;引用和附件按正式位置安排。CLI 保留原始字节与源草稿,不保存审批状态。
|
|
37
|
+
|
|
38
|
+
```powershell
|
|
39
|
+
handbook import-principle docs/research/principle-drafts/design/use-evidence.md --scope design --name use-evidence
|
|
40
|
+
handbook load project:principle:design/use-evidence
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
命令将正文写入当前项目根下的 `docs/knowledge/principles/design/use-evidence/PRINCIPLE.md`,自动创建或补充 `docs/resources.json`。已有有效字段和资源根保留。`FILE` 的相对路径从项目根解析,也可传入已审定草稿的绝对路径。默认同名冲突返回错误,审定修订稿后以 `--replace` 更新已有目标;替换缺失目标和源目标相同也返回错误。
|
|
44
|
+
|
|
45
|
+
输入、声明与目标冲突在写入前失败。普通写入失败及写入后的发现失败返回 `ok: false`,并用 `error.current` 报告声明与正文的实际写入结果;先核对这些结果,再修复原因和重试。完整错误分类及恢复方式见协议的“入库错误与恢复”。首次成功后可直接通过 scopes、list、load 和 validate 消费该原则。
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"tool": "handbook",
|
|
4
|
+
"commands": [
|
|
5
|
+
{
|
|
6
|
+
"name": "scopes",
|
|
7
|
+
"mutation": false,
|
|
8
|
+
"usage": "scopes [--kind workbook|principle]"
|
|
9
|
+
},
|
|
10
|
+
{
|
|
11
|
+
"name": "list",
|
|
12
|
+
"mutation": false,
|
|
13
|
+
"usage": "list [--kind workbook|principle] [--scope SCOPE]"
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
"name": "load",
|
|
17
|
+
"mutation": false,
|
|
18
|
+
"usage": "load ID [ID ...]"
|
|
19
|
+
},
|
|
20
|
+
{
|
|
21
|
+
"name": "validate",
|
|
22
|
+
"mutation": false,
|
|
23
|
+
"usage": "validate"
|
|
24
|
+
},
|
|
25
|
+
{
|
|
26
|
+
"name": "import-principle",
|
|
27
|
+
"mutation": true,
|
|
28
|
+
"usage": "import-principle FILE --scope SCOPE --name NAME [--replace]"
|
|
29
|
+
}
|
|
30
|
+
]
|
|
31
|
+
}
|
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "urn:harness:guides",
|
|
4
|
+
"title": "Work guide headers and resource manifests",
|
|
5
|
+
"$defs": {
|
|
6
|
+
"guideId": {
|
|
7
|
+
"type": "string",
|
|
8
|
+
"pattern": "^[a-z][a-z0-9-]*:(?:workbook:[a-z][a-z0-9-]*|principle:[a-z][a-z0-9]*(?:-[a-z0-9]+)*/[a-z][a-z0-9]*(?:-[a-z0-9]+)*)$"
|
|
9
|
+
},
|
|
10
|
+
"version": {
|
|
11
|
+
"type": "string",
|
|
12
|
+
"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?$"
|
|
13
|
+
},
|
|
14
|
+
"header": {
|
|
15
|
+
"type": "object",
|
|
16
|
+
"additionalProperties": false,
|
|
17
|
+
"required": [
|
|
18
|
+
"name",
|
|
19
|
+
"description"
|
|
20
|
+
],
|
|
21
|
+
"properties": {
|
|
22
|
+
"name": {
|
|
23
|
+
"type": "string",
|
|
24
|
+
"minLength": 1,
|
|
25
|
+
"pattern": "\\S"
|
|
26
|
+
},
|
|
27
|
+
"description": {
|
|
28
|
+
"type": "string",
|
|
29
|
+
"minLength": 1,
|
|
30
|
+
"pattern": "\\S"
|
|
31
|
+
},
|
|
32
|
+
"resourceId": {
|
|
33
|
+
"type": "string",
|
|
34
|
+
"pattern": "^[a-z][a-z0-9-]*:workbook:[a-z][a-z0-9-]*$"
|
|
35
|
+
},
|
|
36
|
+
"includes": {
|
|
37
|
+
"type": "array",
|
|
38
|
+
"uniqueItems": true,
|
|
39
|
+
"minItems": 1,
|
|
40
|
+
"items": {
|
|
41
|
+
"$ref": "#/$defs/guideId"
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
"extensionManifest": {
|
|
47
|
+
"type": "object",
|
|
48
|
+
"additionalProperties": false,
|
|
49
|
+
"required": [
|
|
50
|
+
"schemaVersion",
|
|
51
|
+
"extension",
|
|
52
|
+
"version",
|
|
53
|
+
"resourceRoots",
|
|
54
|
+
"install"
|
|
55
|
+
],
|
|
56
|
+
"properties": {
|
|
57
|
+
"schemaVersion": {
|
|
58
|
+
"const": 1
|
|
59
|
+
},
|
|
60
|
+
"extension": {
|
|
61
|
+
"allOf": [
|
|
62
|
+
{
|
|
63
|
+
"$ref": "urn:harness:common#/$defs/token"
|
|
64
|
+
},
|
|
65
|
+
{
|
|
66
|
+
"not": {
|
|
67
|
+
"enum": [
|
|
68
|
+
"core",
|
|
69
|
+
"project"
|
|
70
|
+
]
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
]
|
|
74
|
+
},
|
|
75
|
+
"version": {
|
|
76
|
+
"$ref": "#/$defs/version"
|
|
77
|
+
},
|
|
78
|
+
"resourceRoots": {
|
|
79
|
+
"type": "array",
|
|
80
|
+
"uniqueItems": true,
|
|
81
|
+
"items": {
|
|
82
|
+
"$ref": "urn:harness:common#/$defs/path"
|
|
83
|
+
}
|
|
84
|
+
},
|
|
85
|
+
"artifactTypes": {
|
|
86
|
+
"type": "array",
|
|
87
|
+
"uniqueItems": true,
|
|
88
|
+
"items": {
|
|
89
|
+
"$ref": "urn:harness:common#/$defs/kindId"
|
|
90
|
+
}
|
|
91
|
+
},
|
|
92
|
+
"relationTypes": {
|
|
93
|
+
"type": "array",
|
|
94
|
+
"uniqueItems": true,
|
|
95
|
+
"items": {
|
|
96
|
+
"$ref": "#/$defs/relationType"
|
|
97
|
+
}
|
|
98
|
+
},
|
|
99
|
+
"install": {
|
|
100
|
+
"$ref": "#/$defs/installEntries"
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
},
|
|
104
|
+
"resourceManifest": {
|
|
105
|
+
"type": "object",
|
|
106
|
+
"additionalProperties": false,
|
|
107
|
+
"required": [
|
|
108
|
+
"schemaVersion",
|
|
109
|
+
"source",
|
|
110
|
+
"version",
|
|
111
|
+
"resourceRoots",
|
|
112
|
+
"install"
|
|
113
|
+
],
|
|
114
|
+
"properties": {
|
|
115
|
+
"schemaVersion": {
|
|
116
|
+
"const": 1
|
|
117
|
+
},
|
|
118
|
+
"source": {
|
|
119
|
+
"$ref": "urn:harness:common#/$defs/token"
|
|
120
|
+
},
|
|
121
|
+
"version": {
|
|
122
|
+
"$ref": "#/$defs/version"
|
|
123
|
+
},
|
|
124
|
+
"resourceRoots": {
|
|
125
|
+
"type": "array",
|
|
126
|
+
"uniqueItems": true,
|
|
127
|
+
"items": {
|
|
128
|
+
"$ref": "urn:harness:common#/$defs/path"
|
|
129
|
+
}
|
|
130
|
+
},
|
|
131
|
+
"artifactTypes": {
|
|
132
|
+
"type": "array",
|
|
133
|
+
"uniqueItems": true,
|
|
134
|
+
"items": {
|
|
135
|
+
"$ref": "urn:harness:common#/$defs/kindId"
|
|
136
|
+
}
|
|
137
|
+
},
|
|
138
|
+
"relationTypes": {
|
|
139
|
+
"type": "array",
|
|
140
|
+
"uniqueItems": true,
|
|
141
|
+
"items": {
|
|
142
|
+
"$ref": "#/$defs/relationType"
|
|
143
|
+
}
|
|
144
|
+
},
|
|
145
|
+
"install": {
|
|
146
|
+
"$ref": "#/$defs/installEntries"
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
},
|
|
150
|
+
"installEntries": {
|
|
151
|
+
"type": "array",
|
|
152
|
+
"uniqueItems": true,
|
|
153
|
+
"items": {
|
|
154
|
+
"type": "object",
|
|
155
|
+
"additionalProperties": false,
|
|
156
|
+
"required": [
|
|
157
|
+
"source",
|
|
158
|
+
"target"
|
|
159
|
+
],
|
|
160
|
+
"properties": {
|
|
161
|
+
"source": {
|
|
162
|
+
"$ref": "urn:harness:common#/$defs/path"
|
|
163
|
+
},
|
|
164
|
+
"target": {
|
|
165
|
+
"$ref": "urn:harness:common#/$defs/path"
|
|
166
|
+
},
|
|
167
|
+
"platforms": {
|
|
168
|
+
"type": "array",
|
|
169
|
+
"minItems": 1,
|
|
170
|
+
"uniqueItems": true,
|
|
171
|
+
"items": {
|
|
172
|
+
"$ref": "urn:harness:common#/$defs/token"
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
},
|
|
178
|
+
"package": {
|
|
179
|
+
"oneOf": [
|
|
180
|
+
{
|
|
181
|
+
"$ref": "#/$defs/extensionManifest"
|
|
182
|
+
},
|
|
183
|
+
{
|
|
184
|
+
"$ref": "#/$defs/resourceManifest"
|
|
185
|
+
}
|
|
186
|
+
]
|
|
187
|
+
},
|
|
188
|
+
"relationType": {
|
|
189
|
+
"type": "object",
|
|
190
|
+
"additionalProperties": false,
|
|
191
|
+
"required": [
|
|
192
|
+
"kind",
|
|
193
|
+
"fromKinds",
|
|
194
|
+
"toKinds",
|
|
195
|
+
"maxOutgoing",
|
|
196
|
+
"maxIncoming",
|
|
197
|
+
"acyclic"
|
|
198
|
+
],
|
|
199
|
+
"properties": {
|
|
200
|
+
"kind": {
|
|
201
|
+
"$ref": "urn:harness:common#/$defs/kindId"
|
|
202
|
+
},
|
|
203
|
+
"fromKinds": {
|
|
204
|
+
"type": "array",
|
|
205
|
+
"minItems": 1,
|
|
206
|
+
"uniqueItems": true,
|
|
207
|
+
"items": {
|
|
208
|
+
"$ref": "urn:harness:common#/$defs/kindId"
|
|
209
|
+
}
|
|
210
|
+
},
|
|
211
|
+
"toKinds": {
|
|
212
|
+
"type": "array",
|
|
213
|
+
"minItems": 1,
|
|
214
|
+
"uniqueItems": true,
|
|
215
|
+
"items": {
|
|
216
|
+
"$ref": "urn:harness:common#/$defs/kindId"
|
|
217
|
+
}
|
|
218
|
+
},
|
|
219
|
+
"maxOutgoing": {
|
|
220
|
+
"type": [
|
|
221
|
+
"integer",
|
|
222
|
+
"null"
|
|
223
|
+
],
|
|
224
|
+
"minimum": 1
|
|
225
|
+
},
|
|
226
|
+
"maxIncoming": {
|
|
227
|
+
"type": [
|
|
228
|
+
"integer",
|
|
229
|
+
"null"
|
|
230
|
+
],
|
|
231
|
+
"minimum": 1
|
|
232
|
+
},
|
|
233
|
+
"acyclic": {
|
|
234
|
+
"type": "boolean"
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
},
|
|
238
|
+
"principleHeader": {
|
|
239
|
+
"type": "object",
|
|
240
|
+
"additionalProperties": false,
|
|
241
|
+
"required": [
|
|
242
|
+
"description"
|
|
243
|
+
],
|
|
244
|
+
"properties": {
|
|
245
|
+
"description": {
|
|
246
|
+
"type": "string",
|
|
247
|
+
"minLength": 1,
|
|
248
|
+
"pattern": "\\S"
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# 项目资源装配与归档协议
|
|
2
|
+
|
|
3
|
+
[harness-install 命令](commands.json)使用[输入 schema](cli.schema.json)和[安装记录 schema](installation.schema.json)。查询 `harness-install install preview --help schema` 和 `harness-install install apply --help` 获取字段与命令细节。
|
|
4
|
+
|
|
5
|
+
## 项目根与资源来源
|
|
6
|
+
|
|
7
|
+
在目标项目根目录运行装配和归档命令。帮助(`-h`/`--help`)与版本(`-v`/`--version`)可在任意目录查看。预览在项目根按 `agent` 查找 `extension-setup-<extension>`,读取其 `assets/extension.json`。受支持的名称为 `codex`、`claude-code`、`pi`。省略 `agent` 时沿用已装配记录的选择,首次默认 `codex`。Codex 与 Pi 共享 `.agents/skills/`,Claude Code 使用 `.claude/skills/`,支持链接或同内容复制。发现同名异源时先统一来源再预览。
|
|
8
|
+
|
|
9
|
+
Vercel skills 安装全局 core Skill 和项目扩展 Skill。全局 `principles`、`workbook` 各自携带 core 资料。`agent` 决定从哪个宿主查找 Skill,adapter 的 `platforms` 单独指定(`codex`、`claude`、`pi-web`)。
|
|
10
|
+
|
|
11
|
+
`extensions` 是希望保留的完整扩展集合。省略时沿用原选择,显式 `[]` 清空全部扩展。增补时列出已选扩展和新增项。本地开发可显式提供绝对路径 `packages`,使用 `extension.json` 或 `resources.json`。其扩展名称须与所选集合一致,可附带 core 源以验证 includes。
|
|
12
|
+
|
|
13
|
+
## 快照与归属
|
|
14
|
+
|
|
15
|
+
[版本 2 项目记录](examples/installation.json)保存目标 `agent`、`stateRevision`、`extensions`(含 `version`)、`platforms` 和受管路径。快照位于 `.agents/extensions/<extension>/`,包含 `extension.json` 以及完整的 `principles/`、`workbooks/` 材料及其配套文件。handbook 与 Project State 读取记录登记的快照。上游 Skill 升级后,在下一次显式装配前继续消费项目中的版本。项目自有资料继续来自 `docs/resources.json`,核心类型与 adapter 随 Python 包发布。
|
|
16
|
+
|
|
17
|
+
每个受管文件保存 `contentDigest`(已安装字节的 SHA-256)。安装和卸载都核对基线,冲突路径在预览显示。卸载保留项目自有文稿和额外文件。声明的 `install` 需要合法相对源、目标与平台;目标归对应扩展所有。Vercel 管理 Skill 目录、宿主 Skill 入口和 `skills-lock.json`。宿主角色 adapter 由安装器从 Python 包复制到 `.codex/agents/`、`.claude/agents/` 或 `.pi/agents/`。
|
|
18
|
+
|
|
19
|
+
## 预览、应用与回执
|
|
20
|
+
|
|
21
|
+
`install preview` 只读,可离线运行。[预览输入](examples/install-preview-input.json)声明需要的扩展和平台。结果包含 `projectRoot`、基准修订号、规范化参数、扩展来源、逐路径新增/更新/移除项与冲突。相同版本与相同字节再次装配时,只有修订记录更新,回执的 `changed` 为 `false`。
|
|
22
|
+
|
|
23
|
+
`install apply` 使用[应用输入](examples/install-apply-input.json)中的完整预览与 `confirmedBy`,并要求 `--request-id req_ID` 和 `--expected-revision N`。命令先核对当前项目根与预览的 `projectRoot`,再持有项目安装锁核对修订号、重建预览并复查来源和目标。来源或目标有变化时刷新预览。最近一次成功的原样请求直接返回已提交回执,同 ID 异参数报 `request_conflict`。
|
|
24
|
+
|
|
25
|
+
首次装配、增补和同步在项目写入前检查目标 agent 的全局 Skill 目录。缺少 `archify` 或 `smell-check` 时,使用 `npx` 执行官方安装命令,可能访问网络并写入该目录。补齐失败时保留受管文件和项目记录,修复后可重试。纯卸载和已提交请求的回执重放可离线运行。
|
|
26
|
+
|
|
27
|
+
最近一次操作保存在 `.harness/previous/`。复制文件原件在 `backup/`,处置与目标登记在 `receipt.json`。写入失败时回退已尝试的文件并记录 `rolled_back`,随后可以重试。安装记录最后写入。遇到强制终止或断电留下的 `applying` 回执时,依据回执和原件恢复后再生成预览。升级装配协议前完成或恢复旧操作,升级后沿用版本 2 项目记录,重新生成预览并使用新的请求 ID。
|
|
28
|
+
|
|
29
|
+
## 明确路径归档
|
|
30
|
+
|
|
31
|
+
`archive PATH [PATH ...]` 接受至少一个项目内相对路径。工具先校验全部路径存在、互不重叠且位于当前项目根,禁止选择 `.git`、`.harness-archive` 及其内部路径。父目录解析后须仍位于项目内。叶节点为符号链接时只移动链接本身。
|
|
32
|
+
|
|
33
|
+
全部校验通过后,工具使用 `rename` 将选定路径原样移入项目根的 `.harness-archive/<UTC批次>/`,保留原相对路径。该命令可离线运行。它将文件视为不透明内容,状态恢复由迁移流程处理。成功返回归档目录 `archive` 与原项目相对路径列表 `paths`。
|
|
34
|
+
|
|
35
|
+
已有项目先停止相关写入并核清范围,用本命令归档待替换的旧运行状态与受管生成材料;项目文档与工具按迁移清单直接移入 `docs/archives/` 分类目录。归档后在干净的活动位置重新安装材料、登记架构身份并按实际产物验收;旧完成状态不作为本次状态依据。
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "urn:harness:installation-cli",
|
|
4
|
+
"$defs": {
|
|
5
|
+
"installPreviewInput": {
|
|
6
|
+
"type": "object",
|
|
7
|
+
"additionalProperties": false,
|
|
8
|
+
"required": [
|
|
9
|
+
"platforms"
|
|
10
|
+
],
|
|
11
|
+
"properties": {
|
|
12
|
+
"packages": {
|
|
13
|
+
"type": "array",
|
|
14
|
+
"minItems": 1,
|
|
15
|
+
"uniqueItems": true,
|
|
16
|
+
"items": {
|
|
17
|
+
"$ref": "urn:harness:common#/$defs/text"
|
|
18
|
+
}
|
|
19
|
+
},
|
|
20
|
+
"extensions": {
|
|
21
|
+
"type": "array",
|
|
22
|
+
"uniqueItems": true,
|
|
23
|
+
"items": {
|
|
24
|
+
"allOf": [
|
|
25
|
+
{
|
|
26
|
+
"$ref": "urn:harness:common#/$defs/token"
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
"not": {
|
|
30
|
+
"enum": [
|
|
31
|
+
"core",
|
|
32
|
+
"project"
|
|
33
|
+
]
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
]
|
|
37
|
+
}
|
|
38
|
+
},
|
|
39
|
+
"platforms": {
|
|
40
|
+
"$ref": "urn:harness:installation#/$defs/platforms"
|
|
41
|
+
},
|
|
42
|
+
"agent": {
|
|
43
|
+
"$ref": "urn:harness:installation#/$defs/agent"
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
},
|
|
47
|
+
"applyInput": {
|
|
48
|
+
"type": "object",
|
|
49
|
+
"additionalProperties": false,
|
|
50
|
+
"required": [
|
|
51
|
+
"preview",
|
|
52
|
+
"confirmedBy"
|
|
53
|
+
],
|
|
54
|
+
"properties": {
|
|
55
|
+
"preview": {
|
|
56
|
+
"$ref": "urn:harness:installation#/$defs/preview"
|
|
57
|
+
},
|
|
58
|
+
"confirmedBy": {
|
|
59
|
+
"$ref": "urn:harness:common#/$defs/actor"
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
},
|
|
63
|
+
"operationResult": {
|
|
64
|
+
"type": "object",
|
|
65
|
+
"additionalProperties": false,
|
|
66
|
+
"required": [
|
|
67
|
+
"operationId",
|
|
68
|
+
"phase",
|
|
69
|
+
"changed",
|
|
70
|
+
"stateRevision"
|
|
71
|
+
],
|
|
72
|
+
"properties": {
|
|
73
|
+
"operationId": {
|
|
74
|
+
"type": "string",
|
|
75
|
+
"pattern": "^operation_[A-Za-z0-9_-]+$"
|
|
76
|
+
},
|
|
77
|
+
"phase": {
|
|
78
|
+
"const": "committed"
|
|
79
|
+
},
|
|
80
|
+
"changed": {
|
|
81
|
+
"type": "boolean"
|
|
82
|
+
},
|
|
83
|
+
"stateRevision": {
|
|
84
|
+
"$ref": "urn:harness:common#/$defs/revision"
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|