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.
Files changed (103) hide show
  1. trigrams_toolkit/__init__.py +1 -0
  2. trigrams_toolkit/handbook/__init__.py +6 -0
  3. trigrams_toolkit/handbook/cli.py +122 -0
  4. trigrams_toolkit/handbook/guide_headers.py +43 -0
  5. trigrams_toolkit/handbook/guides.py +141 -0
  6. trigrams_toolkit/handbook/location.py +79 -0
  7. trigrams_toolkit/handbook/model.py +4 -0
  8. trigrams_toolkit/handbook/package.py +165 -0
  9. trigrams_toolkit/handbook/principle_import.py +101 -0
  10. trigrams_toolkit/handbook/project_resources.py +80 -0
  11. trigrams_toolkit/handbook/skill_sources.py +59 -0
  12. trigrams_toolkit/handbook/source_catalog.py +55 -0
  13. trigrams_toolkit/handbook/sources.py +16 -0
  14. trigrams_toolkit/installation/__init__.py +0 -0
  15. trigrams_toolkit/installation/archive_project.py +50 -0
  16. trigrams_toolkit/installation/global_skills.py +45 -0
  17. trigrams_toolkit/installation/harness_install.py +89 -0
  18. trigrams_toolkit/installation/installation_candidate.py +135 -0
  19. trigrams_toolkit/installation/installation_help.py +49 -0
  20. trigrams_toolkit/installation/installation_materials.py +73 -0
  21. trigrams_toolkit/installation/installation_service.py +14 -0
  22. trigrams_toolkit/installation/installation_sources.py +34 -0
  23. trigrams_toolkit/installation/operation_files.py +94 -0
  24. trigrams_toolkit/installation/operation_runtime.py +144 -0
  25. trigrams_toolkit/installation/package_metadata.py +48 -0
  26. trigrams_toolkit/plan/__init__.py +5 -0
  27. trigrams_toolkit/plan/cli.py +136 -0
  28. trigrams_toolkit/plan/definitions.py +131 -0
  29. trigrams_toolkit/plan/model.py +61 -0
  30. trigrams_toolkit/plan/scheduling.py +126 -0
  31. trigrams_toolkit/plan/service.py +139 -0
  32. trigrams_toolkit/plan/state.py +146 -0
  33. trigrams_toolkit/project_context/__init__.py +16 -0
  34. trigrams_toolkit/project_context/paths.py +36 -0
  35. trigrams_toolkit/py.typed +0 -0
  36. trigrams_toolkit/resources/__init__.py +35 -0
  37. trigrams_toolkit/resources/adapters/claude/README.md +7 -0
  38. trigrams_toolkit/resources/adapters/claude/evaluator.md +7 -0
  39. trigrams_toolkit/resources/adapters/claude/task_developer.md +7 -0
  40. trigrams_toolkit/resources/adapters/codex/README.md +9 -0
  41. trigrams_toolkit/resources/adapters/codex/evaluator.toml +6 -0
  42. trigrams_toolkit/resources/adapters/codex/task_developer.toml +6 -0
  43. trigrams_toolkit/resources/adapters/pi-web/evaluator.md +7 -0
  44. trigrams_toolkit/resources/adapters/pi-web/task_developer.md +7 -0
  45. trigrams_toolkit/resources/handbook/PROTOCOL.md +82 -0
  46. trigrams_toolkit/resources/handbook/README.md +45 -0
  47. trigrams_toolkit/resources/handbook/commands.json +31 -0
  48. trigrams_toolkit/resources/handbook/guides.schema.json +253 -0
  49. trigrams_toolkit/resources/installation/PROTOCOL.md +35 -0
  50. trigrams_toolkit/resources/installation/cli.schema.json +89 -0
  51. trigrams_toolkit/resources/installation/commands.json +23 -0
  52. trigrams_toolkit/resources/installation/examples/install-apply-input.json +48 -0
  53. trigrams_toolkit/resources/installation/examples/install-preview-input.json +7 -0
  54. trigrams_toolkit/resources/installation/examples/installation.json +20 -0
  55. trigrams_toolkit/resources/installation/global-skills.json +6 -0
  56. trigrams_toolkit/resources/installation/installation.schema.json +295 -0
  57. trigrams_toolkit/resources/plan/PROTOCOL.md +89 -0
  58. trigrams_toolkit/resources/plan/README.md +61 -0
  59. trigrams_toolkit/resources/plan/commands.json +36 -0
  60. trigrams_toolkit/resources/plan/plan.schema.json +192 -0
  61. trigrams_toolkit/resources/shared/GLOBAL-TOOLS.md +31 -0
  62. trigrams_toolkit/resources/shared/common.schema.json +234 -0
  63. trigrams_toolkit/resources/state/PROTOCOL.md +85 -0
  64. trigrams_toolkit/resources/state/README.md +88 -0
  65. trigrams_toolkit/resources/state/cli.schema.json +326 -0
  66. trigrams_toolkit/resources/state/commands.json +55 -0
  67. trigrams_toolkit/resources/state/core-types.json +5 -0
  68. trigrams_toolkit/resources/state/help.json +86 -0
  69. trigrams_toolkit/resources/state/sources.schema.json +89 -0
  70. trigrams_toolkit/resources/state/state.schema.json +200 -0
  71. trigrams_toolkit/shared/__init__.py +1 -0
  72. trigrams_toolkit/shared/cli_help.py +195 -0
  73. trigrams_toolkit/shared/errors.py +29 -0
  74. trigrams_toolkit/shared/files.py +66 -0
  75. trigrams_toolkit/shared/locking.py +49 -0
  76. trigrams_toolkit/shared/paths.py +89 -0
  77. trigrams_toolkit/shared/process_lock.py +77 -0
  78. trigrams_toolkit/shared/schema.py +60 -0
  79. trigrams_toolkit/shared/serialization.py +84 -0
  80. trigrams_toolkit/shared/skill_installations.py +66 -0
  81. trigrams_toolkit/shared/state_json.py +45 -0
  82. trigrams_toolkit/state/__init__.py +4 -0
  83. trigrams_toolkit/state/arguments.py +68 -0
  84. trigrams_toolkit/state/cli.py +37 -0
  85. trigrams_toolkit/state/frontmatter.py +176 -0
  86. trigrams_toolkit/state/help.py +25 -0
  87. trigrams_toolkit/state/identity.py +123 -0
  88. trigrams_toolkit/state/location.py +59 -0
  89. trigrams_toolkit/state/model.py +76 -0
  90. trigrams_toolkit/state/providers.py +77 -0
  91. trigrams_toolkit/state/registration.py +82 -0
  92. trigrams_toolkit/state/relations.py +105 -0
  93. trigrams_toolkit/state/service.py +90 -0
  94. trigrams_toolkit/state/store.py +33 -0
  95. trigrams_toolkit/state/views.py +64 -0
  96. trigrams_toolkit/version.py +6 -0
  97. trigrams_toolkit-0.1.0.dist-info/METADATA +69 -0
  98. trigrams_toolkit-0.1.0.dist-info/RECORD +103 -0
  99. trigrams_toolkit-0.1.0.dist-info/WHEEL +5 -0
  100. trigrams_toolkit-0.1.0.dist-info/entry_points.txt +5 -0
  101. trigrams_toolkit-0.1.0.dist-info/licenses/LICENSE +21 -0
  102. trigrams_toolkit-0.1.0.dist-info/licenses/THIRD_PARTY_NOTICES.md +18 -0
  103. trigrams_toolkit-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,192 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:harness:plan",
4
+ "type": "object",
5
+ "additionalProperties": false,
6
+ "required": [
7
+ "status",
8
+ "tasks",
9
+ "stubs"
10
+ ],
11
+ "properties": {
12
+ "status": {
13
+ "$ref": "#/$defs/status"
14
+ },
15
+ "note": {
16
+ "$ref": "#/$defs/text"
17
+ },
18
+ "reason": {
19
+ "$ref": "#/$defs/text"
20
+ },
21
+ "tasks": {
22
+ "type": "object",
23
+ "minProperties": 1,
24
+ "propertyNames": {
25
+ "pattern": "^T[0-9]+$"
26
+ },
27
+ "additionalProperties": {
28
+ "$ref": "#/$defs/task"
29
+ }
30
+ },
31
+ "stubs": {
32
+ "type": "object",
33
+ "propertyNames": {
34
+ "pattern": "^S[0-9]+$"
35
+ },
36
+ "additionalProperties": {
37
+ "$ref": "#/$defs/stub"
38
+ }
39
+ }
40
+ },
41
+ "allOf": [
42
+ {
43
+ "$ref": "#/$defs/reasonRule"
44
+ }
45
+ ],
46
+ "$defs": {
47
+ "status": {
48
+ "enum": [
49
+ "pending",
50
+ "doing",
51
+ "rework",
52
+ "blocked",
53
+ "done",
54
+ "cancelled"
55
+ ]
56
+ },
57
+ "text": {
58
+ "type": "string",
59
+ "minLength": 1,
60
+ "pattern": "\\S"
61
+ },
62
+ "record": {
63
+ "type": "object",
64
+ "additionalProperties": false,
65
+ "required": [
66
+ "status"
67
+ ],
68
+ "properties": {
69
+ "status": {
70
+ "$ref": "#/$defs/status"
71
+ },
72
+ "note": {
73
+ "$ref": "#/$defs/text"
74
+ },
75
+ "reason": {
76
+ "$ref": "#/$defs/text"
77
+ }
78
+ },
79
+ "allOf": [
80
+ {
81
+ "$ref": "#/$defs/reasonRule"
82
+ }
83
+ ]
84
+ },
85
+ "task": {
86
+ "type": "object",
87
+ "additionalProperties": false,
88
+ "required": [
89
+ "status",
90
+ "dependsOn",
91
+ "installs",
92
+ "fills",
93
+ "uses"
94
+ ],
95
+ "properties": {
96
+ "status": {
97
+ "$ref": "#/$defs/status"
98
+ },
99
+ "note": {
100
+ "$ref": "#/$defs/text"
101
+ },
102
+ "reason": {
103
+ "$ref": "#/$defs/text"
104
+ },
105
+ "dependsOn": {
106
+ "type": "array",
107
+ "uniqueItems": true,
108
+ "items": {
109
+ "type": "string",
110
+ "pattern": "^T[0-9]+$"
111
+ }
112
+ },
113
+ "installs": {
114
+ "type": "array",
115
+ "uniqueItems": true,
116
+ "items": {
117
+ "type": "string",
118
+ "pattern": "^S[0-9]+$"
119
+ }
120
+ },
121
+ "fills": {
122
+ "type": "array",
123
+ "uniqueItems": true,
124
+ "items": {
125
+ "type": "string",
126
+ "pattern": "^S[0-9]+$"
127
+ }
128
+ },
129
+ "uses": {
130
+ "type": "array",
131
+ "uniqueItems": true,
132
+ "items": {
133
+ "type": "string",
134
+ "pattern": "^S[0-9]+$"
135
+ }
136
+ }
137
+ },
138
+ "allOf": [
139
+ {
140
+ "$ref": "#/$defs/reasonRule"
141
+ }
142
+ ]
143
+ },
144
+ "stub": {
145
+ "type": "object",
146
+ "additionalProperties": false,
147
+ "required": [
148
+ "name",
149
+ "status"
150
+ ],
151
+ "properties": {
152
+ "name": {
153
+ "$ref": "#/$defs/text"
154
+ },
155
+ "status": {
156
+ "enum": [
157
+ "uninstalled",
158
+ "installed",
159
+ "filled"
160
+ ]
161
+ }
162
+ }
163
+ },
164
+ "reasonRule": {
165
+ "if": {
166
+ "properties": {
167
+ "status": {
168
+ "enum": [
169
+ "blocked",
170
+ "cancelled"
171
+ ]
172
+ }
173
+ },
174
+ "required": [
175
+ "status"
176
+ ]
177
+ },
178
+ "then": {
179
+ "required": [
180
+ "reason"
181
+ ]
182
+ },
183
+ "else": {
184
+ "not": {
185
+ "required": [
186
+ "reason"
187
+ ]
188
+ }
189
+ }
190
+ }
191
+ }
192
+ }
@@ -0,0 +1,31 @@
1
+ # 公共工具与项目接入
2
+
3
+ 公共源码位于 `src/trigrams_toolkit/`。四个公共命令为 plan-toolkit、project-state、handbook、harness-install,由同一 Python 包的标准 console script 提供。
4
+
5
+ ## 分发与运行边界
6
+
7
+ `uv tool install` 安装 CLI,Vercel skills 安装 Skill。包内 `resources/` 是 schema、命令声明、核心类型与 adapter 的维护源,使用 `importlib.resources` 读取;程序版本取自安装包元数据。
8
+
9
+ core 资料随全局 Skill 发布,扩展资料随项目 setup Skill 发布。Project State、Plan 与安装事务各自维护业务文件锁。`harness-install` 在应用装配时按需补齐目标 agent 的全局 Skill。
10
+
11
+ ## 开发依赖
12
+
13
+ Python 最低版本为 3.11,运行与开发依赖在 `pyproject.toml` 单点维护。wheel 和 sdist 携带运行材料与许可;原则、workbook 和 Skill 正文继续使用 Skill 分发渠道。
14
+
15
+ ## 公共解析与文件发布
16
+
17
+ `trigrams_toolkit.shared.serialization` 维护严格 JSON 解析。文档解析入口 `parse_json_document` 拒绝重复键、非整数数值(禁止浮点数与 NaN/Infinity 等常量)、无效 UTF-8 和语法错误,保留协议检查原有的任意精度整数及转义字符串输入。运行时 `parse_json` 在文档解析后核对安全整数范围与 Unicode scalar。`check_protocols` 的 Schema 文档和命令声明读取使用文档边界;现有 Plan、handbook 和安装运行时继续使用运行时边界。解析失败为 `ProtocolError(invalid_json)`;脚本在边界转换为自身错误,文件 I/O 异常由调用方处理。
18
+
19
+ `trigrams_toolkit.shared.files.atomic_write` 负责单文件原子发布、同目录临时文件、文件同步与临时文件清理。Windows 仅对文件占用的权限错误(WinError 5/32 的 PermissionError)作有限重试,持久失败保留异常。项目安装事务负责多文件操作及其回退。
20
+
21
+ ## 项目根
22
+
23
+ 四个公共 CLI 以进程当前目录的实际路径作为项目根。业务命令须在目标项目根执行,各 Git worktree 使用各自根目录。可从任意目录用 `-h` 或 `--help` 查看帮助,用 `-v` 或 `--version` 查看版本。Plan 的成果查询将同一个根交给 Project State 服务。
24
+
25
+ ## 资料与安装
26
+
27
+ handbook 只发现 WORKBOOK.md 和 PRINCIPLE.md。workbook 头维护 name、description 及按需 resourceId、includes;includes 可递归包含 workbook 与 principle。principle 采用 principles/<scope>/<principle>/PRINCIPLE.md,名称、scope 和 ID 从包与目录派生,头信息只接受 description;单条加载只返回自身。list 每项只返回 resourceId、description;load 可批量读取入口,保留正文、来源、入口和 workbook 依赖。Package 声明来源、资料根、成果类型、关系和安装材料。Skill 由宿主发现。
28
+
29
+ `harness-install install preview` 预览项目快照变更,`harness-install install apply` 核对来源声明、路径归属及安装基线后应用。最近一次备份与回执保存在 `.harness/previous`,捕获写入错误后回退。`harness-install archive PATH...` 把明确选择的项目内相对路径原样移入当前项目的 `.harness-archive`,再使用当前工具重建。
30
+
31
+ Plan 与 Task 的状态只属于 plan-toolkit。Module、Feature 与正式成果身份属于 project-state。
@@ -0,0 +1,234 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:harness:common",
4
+ "$defs": {
5
+ "text": {
6
+ "type": "string",
7
+ "minLength": 1,
8
+ "pattern": "\\S"
9
+ },
10
+ "token": {
11
+ "type": "string",
12
+ "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
13
+ },
14
+ "localId": {
15
+ "type": "string",
16
+ "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
17
+ },
18
+ "entityId": {
19
+ "type": "string",
20
+ "pattern": "^(artifact|module|feature)_[A-Za-z0-9_-]+$"
21
+ },
22
+ "artifactId": {
23
+ "type": "string",
24
+ "pattern": "^artifact_[A-Za-z0-9_-]+$"
25
+ },
26
+ "resourceId": {
27
+ "type": "string",
28
+ "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]+)*)$"
29
+ },
30
+ "kindId": {
31
+ "type": "string",
32
+ "pattern": "^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$"
33
+ },
34
+ "timestamp": {
35
+ "type": "string",
36
+ "format": "date-time",
37
+ "pattern": "Z$"
38
+ },
39
+ "revision": {
40
+ "type": "integer",
41
+ "minimum": 0,
42
+ "maximum": 9007199254740991
43
+ },
44
+ "path": {
45
+ "type": "string",
46
+ "minLength": 1,
47
+ "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.?(/|$))(?!.*//)(?!.*[\\\\:*?\"<>|\\u0000-\\u001f])(?!.*[. ](?:/|$))[^/]+(?:/[^/]+)*$"
48
+ },
49
+ "actor": {
50
+ "type": "object",
51
+ "additionalProperties": false,
52
+ "required": [
53
+ "id",
54
+ "kind"
55
+ ],
56
+ "properties": {
57
+ "id": {
58
+ "$ref": "#/$defs/text"
59
+ },
60
+ "kind": {
61
+ "enum": [
62
+ "human",
63
+ "agent",
64
+ "service"
65
+ ]
66
+ }
67
+ }
68
+ },
69
+ "fileRef": {
70
+ "type": "object",
71
+ "additionalProperties": false,
72
+ "required": [
73
+ "kind",
74
+ "root",
75
+ "path"
76
+ ],
77
+ "properties": {
78
+ "kind": {
79
+ "const": "file"
80
+ },
81
+ "root": {
82
+ "enum": [
83
+ "project",
84
+ "plan"
85
+ ]
86
+ },
87
+ "path": {
88
+ "$ref": "#/$defs/path"
89
+ }
90
+ }
91
+ },
92
+ "ref": {
93
+ "oneOf": [
94
+ {
95
+ "$ref": "#/$defs/fileRef"
96
+ },
97
+ {
98
+ "type": "object",
99
+ "additionalProperties": false,
100
+ "required": [
101
+ "kind",
102
+ "id"
103
+ ],
104
+ "properties": {
105
+ "kind": {
106
+ "const": "artifact"
107
+ },
108
+ "id": {
109
+ "$ref": "#/$defs/artifactId"
110
+ }
111
+ }
112
+ },
113
+ {
114
+ "type": "object",
115
+ "additionalProperties": false,
116
+ "required": [
117
+ "kind",
118
+ "id"
119
+ ],
120
+ "properties": {
121
+ "kind": {
122
+ "const": "resource"
123
+ },
124
+ "id": {
125
+ "$ref": "#/$defs/resourceId"
126
+ }
127
+ }
128
+ },
129
+ {
130
+ "type": "object",
131
+ "additionalProperties": false,
132
+ "required": [
133
+ "kind",
134
+ "repository",
135
+ "commit",
136
+ "path"
137
+ ],
138
+ "properties": {
139
+ "kind": {
140
+ "const": "git"
141
+ },
142
+ "repository": {
143
+ "$ref": "#/$defs/text"
144
+ },
145
+ "commit": {
146
+ "type": "string",
147
+ "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
148
+ },
149
+ "path": {
150
+ "$ref": "#/$defs/path"
151
+ }
152
+ }
153
+ },
154
+ {
155
+ "type": "object",
156
+ "additionalProperties": false,
157
+ "required": [
158
+ "kind",
159
+ "uri",
160
+ "version"
161
+ ],
162
+ "properties": {
163
+ "kind": {
164
+ "const": "external"
165
+ },
166
+ "uri": {
167
+ "type": "string",
168
+ "format": "uri"
169
+ },
170
+ "version": {
171
+ "$ref": "#/$defs/text"
172
+ }
173
+ }
174
+ }
175
+ ]
176
+ },
177
+ "refs": {
178
+ "type": "array",
179
+ "uniqueItems": true,
180
+ "items": {
181
+ "$ref": "#/$defs/ref"
182
+ }
183
+ },
184
+ "ids": {
185
+ "type": "array",
186
+ "uniqueItems": true,
187
+ "items": {
188
+ "$ref": "#/$defs/localId"
189
+ }
190
+ },
191
+ "texts": {
192
+ "type": "array",
193
+ "uniqueItems": true,
194
+ "items": {
195
+ "$ref": "#/$defs/text"
196
+ }
197
+ },
198
+ "errorCode": {
199
+ "type": "string",
200
+ "pattern": "^[a-z][a-z0-9_]*$"
201
+ },
202
+ "error": {
203
+ "type": "object",
204
+ "additionalProperties": false,
205
+ "required": [
206
+ "code",
207
+ "message",
208
+ "current",
209
+ "conflicts",
210
+ "recovery"
211
+ ],
212
+ "properties": {
213
+ "code": {
214
+ "$ref": "#/$defs/errorCode"
215
+ },
216
+ "message": {
217
+ "$ref": "#/$defs/text"
218
+ },
219
+ "current": {
220
+ "type": [
221
+ "object",
222
+ "null"
223
+ ]
224
+ },
225
+ "conflicts": {
226
+ "$ref": "#/$defs/texts"
227
+ },
228
+ "recovery": {
229
+ "$ref": "#/$defs/text"
230
+ }
231
+ }
232
+ }
233
+ }
234
+ }
@@ -0,0 +1,85 @@
1
+ # Project State 协议
2
+
3
+ 公开入口由 [commands.json](commands.json) 声明,共 8 个叶子命令。调用方传入位置参数与选项。业务返回 JSON,帮助返回纯文本。具体签名与默认值见 [README](README.md)。
4
+
5
+ ## 项目根
6
+
7
+ 项目根为进程当前工作目录的真实路径。调用方在目标项目根运行命令,相对路径以该根解析。每个 Git worktree 使用自身根目录下的 `.project-state/state.json`。超出项目边界的真实路径返回 `path_outside_root`。Windows 比较忽略大小写,Linux 比较区分大小写。`-h`/`--help` 和 `-v`/`--version` 可在任意目录查看。
8
+
9
+ ## 架构索引
10
+
11
+ [架构索引](state.schema.json) 只保存 Module、Feature、Artifact 与额外关系,`schemaVersion` 固定为 `1`。实体 ID 保持稳定。Artifact 使用 `artifact_` 前缀,CLI 在 YAML 头维护 `artifact-id`,缺失时生成;已有身份保持不变。
12
+
13
+ `register artifact PATH [--kind TYPE] [--module MODULE_ID] [--feature FEATURE_ID]...` 接收归属参数。`--feature` 可重复,要求同次提供 `--module`。提供 Module 时用本次全部 Feature 替换原列表;不传归属参数时沿用索引,首次登记则无归属。头部归属不作为登记输入。工具验证节点存在及 Feature 的树归属,统一写回 `artifact-id`、`moduleId`、`featureIds`;清单模式使用 `id` 身份字段并维护相同归属字段。
14
+
15
+ `relate FROM RELATION TO [--remove]` 维护已声明的额外关系,检查端点类型、基数和环路。RELATION 是关系类型,如 `core:supersedes`,输入契约和存储字段仍名为 `kind`。归属关系从登记参数产生,不能另用 `relate` 维护。相同关系增删按当前状态收敛。
16
+
17
+ ## 公共查询视图
18
+
19
+ `locate`、`related`、`list` 从 Registry 显式投影公共字段,不直接返回内部实体。基础视图如下:
20
+
21
+ | 实体 | 字段 |
22
+ | --- | --- |
23
+ | Module | `id`、`kind: core:module`、`name` |
24
+ | Feature | `id`、`kind: core:feature`、`name`、`moduleId` |
25
+ | Artifact | `id`、`kind`、`title`、可选 `moduleId`、`featureIds` |
26
+
27
+ Artifact 无 Module 归属时省略 `moduleId`,无 Feature 归属时返回 `featureIds: []`。`name` 与 `title` 沿用各实体的名称字段。查询不返回 `locatorHint`、`identityMode`、`entity`、`message`、`specs` 或 `viaModule`。注册命令仍沿用原返回契约,内部索引字段与 schema 不变。
28
+
29
+ ### 单实体定位
30
+
31
+ `locate ID` 的 `data` 直接承载目标视图。Module、Feature 只返回基础字段,不返回 `path`。Artifact 在基础字段上附加按身份定位得到的绝对 `path`;清单型 Artifact 的 `path` 指向清单文件。
32
+
33
+ 定位按身份扫描项目根下的 `docs/`、`plans/` 以及已登记的路径提示。默认扫描跳过 `docs/archives/`,明确登记的路径提示仍可定位。正文移动后,处于扫描范围内即可通过身份查找。`locate` 不查询关联文稿,也不沿 Feature 的 `moduleId` 展开 Module 文稿。无关文稿或邻接文稿失联不影响本次单实体定位。
34
+
35
+ ### 一跳关联查询
36
+
37
+ `related ID [--direction DIRECTION]` 的 `data` 只包含 `items` 和 `relations`。`items` 使用 `locate` 的实体视图,Artifact 附加实际绝对 `path`。每个邻接实体 ID 只出现一次,目标自身不进入 `items`。`relations` 保留所有匹配关系,同一对端点之间的不同关系不合并。
38
+
39
+ 直接关联取自登记产生的归属关系和显式额外关系。每条关系包含 `kind/from/to/source`,方向只按 `from/to` 判断:
40
+
41
+ | 关系 | 方向 | `source` |
42
+ | --- | --- | --- |
43
+ | `core:feature-module` | Feature → Module | `feature` |
44
+ | `core:module-spec` | Module → 声明该 `moduleId` 的 Artifact | `document` |
45
+ | `core:feature-spec` | Feature → `featureIds` 含该 Feature 的 Artifact | `document` |
46
+ | 显式额外关系 | 登记的 `from` → `to` | `relation` |
47
+
48
+ `direction` 默认为 `both`。`outgoing` 只保留 `from` 为目标 ID 的边,`incoming` 只保留 `to` 为目标 ID 的边,`both` 保留两者。查询先筛选关系,再定位邻接 Artifact,只遍历一条边。无关文稿或方向筛选掉的文稿不触发定位错误。
49
+
50
+ Feature 的 Module 是直接邻居,Module 的其他文稿不因此进入结果。Module 直接关联所有声明该 `moduleId` 的 Artifact,包括同时归属于 Feature 的文稿。跨 Module 的显式关系按实际端点返回。无邻居时返回 `items: []` 与 `relations: []`。
51
+
52
+ 查询模块文稿时,运行 `related <Module ID>`,读取 `data.items` 中 Artifact 的 `path`。从 Feature 导航模块资料时,先读取 `locate <Feature ID>` 的 `data.moduleId`,或读取 `related <Feature ID>` 中的 Module,再主动查询该 Module。
53
+
54
+ ### 枚举与失败语义
55
+
56
+ `list [--kind TYPE]` 保留 `data.items`、既有类型筛选及按 ID 的排序规则。每项只使用基础视图,不解析或返回 `path`。失联文稿仍可枚举,实际路径通过 `locate` 获取。
57
+
58
+ `locate` 与 `related` 的目标未注册时返回 `invalid_reference`。本次应返回路径的 Artifact 无身份正文时返回 `invalid_reference`,多份正文声明同一身份时返回 `identity_conflict`。定位失败沿用现有错误信封,整体查询失败,不返回部分成功结果。路径边界、索引读取与 IO 错误继续透传。
59
+
60
+ 三类查询的输出分别由 [cli.schema.json](cli.schema.json) 的 `locateResponse`、`relatedResponse`、`listResponse` 约束。[commands.json](commands.json) 引用对应定义;其他命令保留既有信封契约。
61
+
62
+ 本次查询输出为破坏性变更,不保留旧字段别名。`plan-toolkit inspect` 的 `data.specs` 仍表示 Task 正式输入,继续逐项接收 `locate` 的路径或错误。
63
+
64
+ ## Artifact 类型
65
+
66
+ Artifact 的类型使用 Registry 中的 `kind` 字段,登记时通过 `--kind` 指定。core 类型名称由 [core-types.json](core-types.json) 声明,语义如下:
67
+
68
+ | `kind` | 用途 |
69
+ | --- | --- |
70
+ | `core:document` | 通用文档,适用于未采用专门类型的文稿 |
71
+ | `core:architecture-spec` | Module 的实现设计与契约,即 Implementation Spec,定义所属 Feature 的行为、接口、状态和运行约束 |
72
+ | `core:code-architecture` | 整体代码架构与工程组织文档,如 DEVTECH、ARD,定义技术栈、架构分层、Module / Feature 边界和依赖方向 |
73
+ | `core:review` | 交付审核报告,记录审核结论、问题与验证证据 |
74
+
75
+ 调用方登记上述专门类型的文稿时,应显式传入对应的 `--kind`,并在交接待登记信息时提供该类型。CLI 不根据文件名、目录、标题或正文推断类型。省略 `--kind` 时,已登记 Artifact 沿用原类型,首次登记使用 `core:document`。显式传入 `--kind` 可更新已有 Artifact 的类型,身份保持不变。
76
+
77
+ `kind` 只保存在 Registry,不写入 YAML 头。类型用于 `list --kind` 筛选及额外关系的端点校验。`locate` 按 ID 定位,`related` 按直接关系查询,两者都不按 `core:architecture-spec` 限制 Artifact 类型。
78
+
79
+ ## 写入
80
+
81
+ 写入持有索引文件锁,用同目录临时文件原子替换。校验失败不改写文稿或索引。文件头先于索引落盘,两次写入不是跨文件原子事务;若索引写入失败,以相同参数重试会复用已有身份。仅文件头修复也返回 `changed: true`。新节点创建的结果不确定时,调用方先查询已有节点。
82
+
83
+ 格式不符时,命令返回 `invalid_schema`。调用方先归档原状态,再按 `initialize` workbook 重新登记。
84
+
85
+ CLI 的输入与响应目录见 [cli.schema.json](cli.schema.json)。这些 schema 用于本地契约验证。
@@ -0,0 +1,88 @@
1
+ # Project State
2
+
3
+ Project State 登记 Module、Feature 和正式文稿的身份、归属与额外关系。Plan 和 Task 的状态由 Plan 工具维护。
4
+
5
+ ## 命令
6
+
7
+ | 命令 | 用途 |
8
+ | --- | --- |
9
+ | `register module NAME [--id ID]` | 新建 Module,或按 ID 更新名称 |
10
+ | `register feature NAME [--module MODULE_ID] [--id ID]` | 新建或更新 Feature;新建时提供 Module,更新时可沿用归属 |
11
+ | `register artifact PATH [--kind TYPE] [--module MODULE_ID] [--feature FEATURE_ID]...` | 读取文稿身份与标题,根据参数维护归属、文件头和索引 |
12
+ | `locate ID` | 只返回目标的公共视图;Artifact 附加实际绝对路径 |
13
+ | `list [--kind TYPE]` | 列出基础公共视图,不解析路径;可按 module、feature、artifact 或完整类型筛选 |
14
+ | `related ID [--direction DIRECTION]` | 返回一跳邻居与关系;Artifact 邻居附加路径;方向默认为 both,也可选 incoming、outgoing |
15
+ | `relate FROM RELATION TO [--remove]` | 增删已声明的额外关系;RELATION 是关系类型名 |
16
+ | `validate` | 检查身份、文件头与索引的归属一致性及关系;索引不存在时也可运行 |
17
+
18
+ 在目标项目根执行命令。`-h`/`--help` 和 `-v`/`--version` 可在任意目录查看。帮助为纯文本,业务结果为 `{ "ok": true, "data": ... }`,错误为 `{ "ok": false, "error": { "code": ..., "message": ... } }`。成功退出码为 0,失败为 1。
19
+
20
+ 相对路径从当前目录解析,项目根与文稿边界按真实路径判断。Windows 短路径和目录链接沿用真实目录的身份。Windows 路径比较忽略大小写,Linux 路径比较区分大小写。每个 Git worktree 使用自身的项目根和索引。
21
+
22
+ 新 Module、Feature 省略 `--id` 时,工具分别生成 `module_`、`feature_` 加 10 位随机后缀的 ID,返回于 `data.entity.id`。名称是独立字段,同名登记不会自动复用身份。若上次创建的结果不确定,先用 `list` 核对。调用方可以提供符合格式的稳定 `--id`;更新已有节点时传入原 ID,Feature 省略 `--module` 会沿用原归属。这两个命令只维护索引,调用方负责将 ID 回填到 ARD 节点,并同步节点名称与树位置。
23
+
24
+ ## 查询与资料导航
25
+
26
+ `locate` 的 `data` 直接包含目标字段。Module 返回 `id/kind/name`,Feature 另有 `moduleId`。Artifact 返回 `id/kind/title/featureIds/path`,有 Module 归属时另有 `moduleId`。无 Feature 归属时,`featureIds` 为空数组。清单型 Artifact 的 `path` 指向清单文件。
27
+
28
+ `related` 的 `data` 只包含 `items` 和 `relations`。`items` 使用与 `locate` 相同的公共字段,每个邻居只出现一次;`relations` 保留匹配边的 `kind/from/to/source`。查询只遍历一条边,先按方向筛选,再定位邻接文稿。Feature 的 Module 是直接邻居,Module 的其他文稿不自动进入结果。
29
+
30
+ 查询模块资料时,运行 `project-state related <Module ID>`,读取 `data.items` 中 Artifact 的 `path`。从 Feature 导航时,可用 `locate <Feature ID>` 的 `data.moduleId`,或 `related <Feature ID>` 返回的 Module,再主动查询模块。每次调用检查退出码为 0 和 `ok: true`。
31
+
32
+ `list` 保留 `data.items`、类型筛选和按 ID 排序,每项采用基础公共字段,不返回 `path`。失联文稿仍可枚举。`locate` 与 `related` 的目标未登记或本次应定位的正文缺失时返回 `invalid_reference`,正文身份重复时返回 `identity_conflict`,整体查询失败。无关文稿和方向筛选掉的文稿失联不影响查询。
33
+
34
+ 本次查询输出有破坏性变化:删除旧 `entity/message/specs/viaModule` 包装,停止 Feature 自动展开 Module 文稿。三个查询均不再返回内部 `locatorHint/identityMode`。注册返回契约不变;`plan-toolkit inspect` 的 `data.specs` 仍表示 Task 的正式输入。
35
+
36
+ ## 文稿登记
37
+
38
+ 调度 Agent 通过命令参数提交正式文稿的归属。文稿作者保留已有身份,交付路径与归属信息,不必预填 YAML 头:
39
+
40
+ ```powershell
41
+ project-state register artifact docs/inventory.md --kind core:architecture-spec --module module_inventory --feature feature_slots --feature feature_sorting
42
+ ```
43
+
44
+ `--feature` 可重复使用,每次传入一个 Feature ID,并要求同次提供 `--module`。CLI 校验节点存在、Feature 属于该 Module 且列表不重复,然后统一写回文件头与索引:
45
+
46
+ ```yaml
47
+ ---
48
+ artifact-id: artifact_inventory
49
+ moduleId: module_inventory
50
+ featureIds: [feature_slots, feature_sorting]
51
+ ---
52
+ # Inventory Spec
53
+ ```
54
+
55
+ `artifact-id` 缺失时,登记会生成并写入身份。Artifact ID 使用 `artifact_` 前缀,示例中的可读 ID 代表已有身份;自动生成的 ID 使用 10 位随机后缀。重复登记复用 YAML 头中的身份。标题优先读取 `title`,其次读取首个一级标题,最后使用文件名。
56
+
57
+ 首次登记不传归属参数时,文稿无归属。已登记文稿不传归属参数时,沿用索引中已接受的归属。传入 `--module` 时,用该 Module 和本次全部 `--feature` 替换原归属;只传 `--module` 就清空 Feature 列表。
58
+
59
+ `artifact-id`、`moduleId`、`featureIds` 由工具维护。手改头部不会改变登记归属;`validate` 会报告与索引不符的归属,重新登记会按已有索引或本次参数恢复头部。其他头部字段、注释与文稿内容保留,头部由 YAML 解析器序列化,排版可随之调整。归属关联由索引展开,`relate` 不重复维护这组关联。
60
+
61
+ Artifact 的 `kind` 表示文稿类型,只保存在索引,不写入 YAML 头。登记专门类型时显式传入 `--kind`;Implementation Spec 使用 `core:architecture-spec`,其他 core 类型见 [Artifact 类型契约](PROTOCOL.md#artifact-类型)。省略时沿用已登记类型,首次登记使用 `core:document`;CLI 不根据文稿内容推断类型。已有文稿可用原路径和 `--kind` 更新类型,省略归属参数即可保留原归属。
62
+
63
+ 核心类型与额外关系随 Python 包发布。扩展类型通过项目安装记录读取快照声明,项目类型继续来自 `docs/resources.json`。
64
+
65
+ 二进制成果可使用带 `schemaVersion: 1`、`id`、`members` 的身份清单登记。相同归属参数写入清单的 `moduleId`、`featureIds`,成员路径相对于项目根。正文定位按身份扫描 `docs/` 和 `plans/`,跳过 `docs/archives/` 的自动扫描,并检查索引中已有的路径提示。移动正文后,在扫描范围内仍可定位。
66
+
67
+ ## 额外关系
68
+
69
+ `relate FROM RELATION TO [--remove]` 的 RELATION 是关系类型,与文稿的 `--kind` 不同。例如 `relate artifact_new core:supersedes artifact_old` 表示前者取代后者;两端应为同类型 Artifact。项目或扩展还可声明额外关系类型。`--remove` 只删除关系,不修改文稿。Feature 的 Module 归属通过 `register feature --module` 维护,文稿归属通过 `register artifact --module --feature` 维护。
70
+
71
+ ## 存储
72
+
73
+ 索引的 `schemaVersion` 固定为 `1`,保存在项目根的 `.project-state/state.json`。内容只有 Module、Feature、Artifact 和额外关系。写入使用文件锁与同目录原子替换,锁冲突直接报错。登记先验证身份与归属,再写文件头,最后写索引。两份文件不构成原子事务。索引失败后以相同归属参数重跑,仍复用同一身份。仅修复文件头时,结果中的 `changed` 也为 `true`。
74
+
75
+ 格式不符时,命令返回 `invalid_schema`。先归档原状态,再按 `initialize` workbook 重新登记。
76
+
77
+ ## 开发与验证
78
+
79
+ Project State 与其余三个 CLI 共用 Python 3.11+ 包、依赖和版本。安装可编辑包后,在仓库根执行:
80
+
81
+ ```sh
82
+ python -m mypy
83
+ python -m unittest discover -s tests -p 'test_project_*.py' -v
84
+ python tasks.py build
85
+ python tasks.py verify-package
86
+ ```
87
+
88
+ 测试使用 `.tmp/` 的隔离项目,覆盖身份、归属、查询、文稿保真、关系、锁和 Git worktree。平台回归覆盖含中文与空格的路径、真实路径、目录链接、Windows 短路径与 Linux 大小写。包验收从隔离项目根调用标准入口,回执写入指定 output。