@carloswon/cairn-memory 0.0.0-stage → 0.2.0

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 (222) hide show
  1. package/CHANGELOG.md +54 -0
  2. package/LICENSE +21 -0
  3. package/README.md +158 -2
  4. package/dist/src/agents/adapters.d.ts +82 -0
  5. package/dist/src/agents/adapters.js +209 -0
  6. package/dist/src/agents/adapters.js.map +1 -0
  7. package/dist/src/agents/config.d.ts +82 -0
  8. package/dist/src/agents/config.js +603 -0
  9. package/dist/src/agents/config.js.map +1 -0
  10. package/dist/src/agents/cordisPatch.d.ts +89 -0
  11. package/dist/src/agents/cordisPatch.js +201 -0
  12. package/dist/src/agents/cordisPatch.js.map +1 -0
  13. package/dist/src/agents/index.d.ts +2 -0
  14. package/dist/src/agents/index.js +3 -0
  15. package/dist/src/agents/index.js.map +1 -0
  16. package/dist/src/core/errors.d.ts +36 -0
  17. package/dist/src/core/errors.js +74 -0
  18. package/dist/src/core/errors.js.map +1 -0
  19. package/dist/src/core/hash.d.ts +14 -0
  20. package/dist/src/core/hash.js +48 -0
  21. package/dist/src/core/hash.js.map +1 -0
  22. package/dist/src/core/ids.d.ts +10 -0
  23. package/dist/src/core/ids.js +41 -0
  24. package/dist/src/core/ids.js.map +1 -0
  25. package/dist/src/core/index.d.ts +6 -0
  26. package/dist/src/core/index.js +7 -0
  27. package/dist/src/core/index.js.map +1 -0
  28. package/dist/src/core/scope.d.ts +78 -0
  29. package/dist/src/core/scope.js +181 -0
  30. package/dist/src/core/scope.js.map +1 -0
  31. package/dist/src/core/secrets.d.ts +13 -0
  32. package/dist/src/core/secrets.js +122 -0
  33. package/dist/src/core/secrets.js.map +1 -0
  34. package/dist/src/core/time.d.ts +7 -0
  35. package/dist/src/core/time.js +18 -0
  36. package/dist/src/core/time.js.map +1 -0
  37. package/dist/src/core/types.d.ts +133 -0
  38. package/dist/src/core/types.js +30 -0
  39. package/dist/src/core/types.js.map +1 -0
  40. package/dist/src/governance/apply.d.ts +64 -0
  41. package/dist/src/governance/apply.js +160 -0
  42. package/dist/src/governance/apply.js.map +1 -0
  43. package/dist/src/governance/dedup.d.ts +21 -0
  44. package/dist/src/governance/dedup.js +23 -0
  45. package/dist/src/governance/dedup.js.map +1 -0
  46. package/dist/src/governance/index.d.ts +16 -0
  47. package/dist/src/governance/index.js +17 -0
  48. package/dist/src/governance/index.js.map +1 -0
  49. package/dist/src/governance/propose.d.ts +78 -0
  50. package/dist/src/governance/propose.js +150 -0
  51. package/dist/src/governance/propose.js.map +1 -0
  52. package/dist/src/index.d.ts +15 -0
  53. package/dist/src/index.js +24 -0
  54. package/dist/src/index.js.map +1 -0
  55. package/dist/src/interfaces/app-service.d.ts +242 -0
  56. package/dist/src/interfaces/app-service.js +614 -0
  57. package/dist/src/interfaces/app-service.js.map +1 -0
  58. package/dist/src/interfaces/cli/main.d.ts +2 -0
  59. package/dist/src/interfaces/cli/main.js +790 -0
  60. package/dist/src/interfaces/cli/main.js.map +1 -0
  61. package/dist/src/interfaces/console/assets/page.d.ts +18 -0
  62. package/dist/src/interfaces/console/assets/page.js +39 -0
  63. package/dist/src/interfaces/console/assets/page.js.map +1 -0
  64. package/dist/src/interfaces/console/assets/ui-css.d.ts +11 -0
  65. package/dist/src/interfaces/console/assets/ui-css.js +119 -0
  66. package/dist/src/interfaces/console/assets/ui-css.js.map +1 -0
  67. package/dist/src/interfaces/console/assets/ui-js.d.ts +14 -0
  68. package/dist/src/interfaces/console/assets/ui-js.js +1098 -0
  69. package/dist/src/interfaces/console/assets/ui-js.js.map +1 -0
  70. package/dist/src/interfaces/console/assets/url-state.d.ts +9 -0
  71. package/dist/src/interfaces/console/assets/url-state.js +45 -0
  72. package/dist/src/interfaces/console/assets/url-state.js.map +1 -0
  73. package/dist/src/interfaces/console/export.d.ts +46 -0
  74. package/dist/src/interfaces/console/export.js +84 -0
  75. package/dist/src/interfaces/console/export.js.map +1 -0
  76. package/dist/src/interfaces/console/model.d.ts +372 -0
  77. package/dist/src/interfaces/console/model.js +731 -0
  78. package/dist/src/interfaces/console/model.js.map +1 -0
  79. package/dist/src/interfaces/console/review-store.d.ts +142 -0
  80. package/dist/src/interfaces/console/review-store.js +342 -0
  81. package/dist/src/interfaces/console/review-store.js.map +1 -0
  82. package/dist/src/interfaces/console/security.d.ts +76 -0
  83. package/dist/src/interfaces/console/security.js +105 -0
  84. package/dist/src/interfaces/console/security.js.map +1 -0
  85. package/dist/src/interfaces/console/server.d.ts +45 -0
  86. package/dist/src/interfaces/console/server.js +476 -0
  87. package/dist/src/interfaces/console/server.js.map +1 -0
  88. package/dist/src/interfaces/console/suggestions.d.ts +112 -0
  89. package/dist/src/interfaces/console/suggestions.js +511 -0
  90. package/dist/src/interfaces/console/suggestions.js.map +1 -0
  91. package/dist/src/interfaces/console/text.d.ts +4 -0
  92. package/dist/src/interfaces/console/text.js +18 -0
  93. package/dist/src/interfaces/console/text.js.map +1 -0
  94. package/dist/src/interfaces/mcp/server.d.ts +4 -0
  95. package/dist/src/interfaces/mcp/server.js +412 -0
  96. package/dist/src/interfaces/mcp/server.js.map +1 -0
  97. package/dist/src/jobs/index.d.ts +6 -0
  98. package/dist/src/jobs/index.js +7 -0
  99. package/dist/src/jobs/index.js.map +1 -0
  100. package/dist/src/jobs/remote.d.ts +42 -0
  101. package/dist/src/jobs/remote.js +34 -0
  102. package/dist/src/jobs/remote.js.map +1 -0
  103. package/dist/src/jobs/worker.d.ts +67 -0
  104. package/dist/src/jobs/worker.js +169 -0
  105. package/dist/src/jobs/worker.js.map +1 -0
  106. package/dist/src/onboarding/auto.d.ts +88 -0
  107. package/dist/src/onboarding/auto.js +399 -0
  108. package/dist/src/onboarding/auto.js.map +1 -0
  109. package/dist/src/onboarding/batches.d.ts +103 -0
  110. package/dist/src/onboarding/batches.js +219 -0
  111. package/dist/src/onboarding/batches.js.map +1 -0
  112. package/dist/src/onboarding/discover.d.ts +54 -0
  113. package/dist/src/onboarding/discover.js +369 -0
  114. package/dist/src/onboarding/discover.js.map +1 -0
  115. package/dist/src/onboarding/import.d.ts +69 -0
  116. package/dist/src/onboarding/import.js +279 -0
  117. package/dist/src/onboarding/import.js.map +1 -0
  118. package/dist/src/onboarding/index.d.ts +24 -0
  119. package/dist/src/onboarding/index.js +22 -0
  120. package/dist/src/onboarding/index.js.map +1 -0
  121. package/dist/src/onboarding/judgement.d.ts +50 -0
  122. package/dist/src/onboarding/judgement.js +121 -0
  123. package/dist/src/onboarding/judgement.js.map +1 -0
  124. package/dist/src/onboarding/policy.d.ts +86 -0
  125. package/dist/src/onboarding/policy.js +249 -0
  126. package/dist/src/onboarding/policy.js.map +1 -0
  127. package/dist/src/projection/brief.d.ts +77 -0
  128. package/dist/src/projection/brief.js +111 -0
  129. package/dist/src/projection/brief.js.map +1 -0
  130. package/dist/src/projection/index.d.ts +1 -0
  131. package/dist/src/projection/index.js +2 -0
  132. package/dist/src/projection/index.js.map +1 -0
  133. package/dist/src/projection/markdown.d.ts +82 -0
  134. package/dist/src/projection/markdown.js +313 -0
  135. package/dist/src/projection/markdown.js.map +1 -0
  136. package/dist/src/retrieval/export.d.ts +80 -0
  137. package/dist/src/retrieval/export.js +215 -0
  138. package/dist/src/retrieval/export.js.map +1 -0
  139. package/dist/src/retrieval/index.d.ts +5 -0
  140. package/dist/src/retrieval/index.js +6 -0
  141. package/dist/src/retrieval/index.js.map +1 -0
  142. package/dist/src/retrieval/search.d.ts +37 -0
  143. package/dist/src/retrieval/search.js +294 -0
  144. package/dist/src/retrieval/search.js.map +1 -0
  145. package/dist/src/store/archives.d.ts +94 -0
  146. package/dist/src/store/archives.js +135 -0
  147. package/dist/src/store/archives.js.map +1 -0
  148. package/dist/src/store/audit.d.ts +26 -0
  149. package/dist/src/store/audit.js +48 -0
  150. package/dist/src/store/audit.js.map +1 -0
  151. package/dist/src/store/backup.d.ts +36 -0
  152. package/dist/src/store/backup.js +90 -0
  153. package/dist/src/store/backup.js.map +1 -0
  154. package/dist/src/store/blocks.d.ts +64 -0
  155. package/dist/src/store/blocks.js +104 -0
  156. package/dist/src/store/blocks.js.map +1 -0
  157. package/dist/src/store/conflicts.d.ts +52 -0
  158. package/dist/src/store/conflicts.js +112 -0
  159. package/dist/src/store/conflicts.js.map +1 -0
  160. package/dist/src/store/db.d.ts +44 -0
  161. package/dist/src/store/db.js +162 -0
  162. package/dist/src/store/db.js.map +1 -0
  163. package/dist/src/store/device.d.ts +46 -0
  164. package/dist/src/store/device.js +111 -0
  165. package/dist/src/store/device.js.map +1 -0
  166. package/dist/src/store/index.d.ts +14 -0
  167. package/dist/src/store/index.js +15 -0
  168. package/dist/src/store/index.js.map +1 -0
  169. package/dist/src/store/memories.d.ts +101 -0
  170. package/dist/src/store/memories.js +378 -0
  171. package/dist/src/store/memories.js.map +1 -0
  172. package/dist/src/store/migrate.d.ts +32 -0
  173. package/dist/src/store/migrate.js +86 -0
  174. package/dist/src/store/migrate.js.map +1 -0
  175. package/dist/src/store/open.d.ts +53 -0
  176. package/dist/src/store/open.js +177 -0
  177. package/dist/src/store/open.js.map +1 -0
  178. package/dist/src/store/outbox.d.ts +65 -0
  179. package/dist/src/store/outbox.js +137 -0
  180. package/dist/src/store/outbox.js.map +1 -0
  181. package/dist/src/store/plans.d.ts +137 -0
  182. package/dist/src/store/plans.js +243 -0
  183. package/dist/src/store/plans.js.map +1 -0
  184. package/dist/src/store/schema.d.ts +34 -0
  185. package/dist/src/store/schema.js +527 -0
  186. package/dist/src/store/schema.js.map +1 -0
  187. package/dist/src/store/scopes.d.ts +44 -0
  188. package/dist/src/store/scopes.js +220 -0
  189. package/dist/src/store/scopes.js.map +1 -0
  190. package/dist/src/store/write-guard.d.ts +10 -0
  191. package/dist/src/store/write-guard.js +10 -0
  192. package/dist/src/store/write-guard.js.map +1 -0
  193. package/dist/src/sync/apply.d.ts +24 -0
  194. package/dist/src/sync/apply.js +130 -0
  195. package/dist/src/sync/apply.js.map +1 -0
  196. package/dist/src/sync/cryptoutil.d.ts +86 -0
  197. package/dist/src/sync/cryptoutil.js +339 -0
  198. package/dist/src/sync/cryptoutil.js.map +1 -0
  199. package/dist/src/sync/events.d.ts +69 -0
  200. package/dist/src/sync/events.js +78 -0
  201. package/dist/src/sync/events.js.map +1 -0
  202. package/dist/src/sync/obs-store.d.ts +41 -0
  203. package/dist/src/sync/obs-store.js +325 -0
  204. package/dist/src/sync/obs-store.js.map +1 -0
  205. package/dist/src/sync/orchestrate.d.ts +37 -0
  206. package/dist/src/sync/orchestrate.js +84 -0
  207. package/dist/src/sync/orchestrate.js.map +1 -0
  208. package/dist/src/sync/pull.d.ts +24 -0
  209. package/dist/src/sync/pull.js +150 -0
  210. package/dist/src/sync/pull.js.map +1 -0
  211. package/dist/src/sync/push.d.ts +19 -0
  212. package/dist/src/sync/push.js +227 -0
  213. package/dist/src/sync/push.js.map +1 -0
  214. package/dist/src/sync/syncd-store.d.ts +31 -0
  215. package/dist/src/sync/syncd-store.js +92 -0
  216. package/dist/src/sync/syncd-store.js.map +1 -0
  217. package/dist/src/sync/vault.d.ts +37 -0
  218. package/dist/src/sync/vault.js +53 -0
  219. package/dist/src/sync/vault.js.map +1 -0
  220. package/docs/cairn-security.md +254 -0
  221. package/docs/cairn-usage.md +821 -0
  222. package/package.json +71 -4
@@ -0,0 +1,219 @@
1
+ import { uuidv7 } from '../core/ids.js';
2
+ import { err } from '../core/errors.js';
3
+ /**
4
+ * 分批与续跑(任务 4.3 / spec agent-onboarding「对话式分批初始化」):
5
+ *
6
+ * 当前 Agent 只能读取 nextBatchChunk 吐出的批次切片(clean 且未晋升、有界
7
+ * limit)来生成治理建议;markItemPromoted 在真实批准并晋升后打标记。
8
+ * 会话中断后重开库,nextBatchChunk 的游标(已晋升不再返回)与进度都从
9
+ * 持久状态恢复,不重复已应用操作,也不扩大原授权范围。
10
+ *
11
+ * 晋升状态的承载方式(刻意设计:审计即状态):
12
+ * - schema 已冻结(design Migration Plan),不能给 import_item 加晋升列;
13
+ * - 晋升映射写入 audit_event:category='onboarding'、action='item_promoted'、
14
+ * subject={type:'import_item', id:itemId}、detail={"itemId","memoryId"};
15
+ * - 所有"这条还需要处理吗"的判断统一走 promotedPredicate()(审计存在即已晋升);
16
+ * - 好处:晋升动作本身永远是可审计事件(谁在何时晋升了哪条到哪条记忆),
17
+ * 状态与审计天然一致,且跨会话持久。
18
+ */
19
+ const PROMOTED_CATEGORY = 'onboarding';
20
+ const PROMOTED_ACTION = 'item_promoted';
21
+ /**
22
+ * 跳过事实的动作名。
23
+ *
24
+ * 刻意与 item_promoted 分开:后者只表示「确实生成了记忆」。若让一个动作兼表两义,
25
+ * 「已晋升」这个唯一谓词就对所有消费方说谎,而审计只增不改、污染后不可逆。
26
+ */
27
+ const SKIPPED_ACTION = 'item_skipped';
28
+ export function promotedPredicate(alias = 'i') {
29
+ // 允许 console/model.ts 的 %ALIAS% 占位符(它做字符串替换后再拼接)。
30
+ if (alias !== '%ALIAS%' && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
31
+ throw err('E_VALIDATION', `非法 SQL 别名: ${alias}`);
32
+ }
33
+ const fact = (action) => `EXISTS (
34
+ SELECT 1 FROM audit_event a
35
+ WHERE a.category = '${PROMOTED_CATEGORY}' AND a.action = '${action}'
36
+ AND json_extract(a.detail, '$.itemId') = ${alias}.id)`;
37
+ const exists = fact(PROMOTED_ACTION);
38
+ const skippedExists = fact(SKIPPED_ACTION);
39
+ const handledExists = `(${exists} OR ${skippedExists})`;
40
+ return {
41
+ exists,
42
+ notExists: `NOT ${exists}`,
43
+ skippedExists,
44
+ skippedNotExists: `NOT ${skippedExists}`,
45
+ handledExists,
46
+ handledNotExists: `NOT ${handledExists}`,
47
+ };
48
+ }
49
+ const { exists: PROMOTED_EXISTS, notExists: PROMOTED_NOT_EXISTS, skippedExists: SKIPPED_EXISTS, handledNotExists: HANDLED_NOT_EXISTS, } = promotedPredicate('i');
50
+ /**
51
+ * 给 archive 未分批(batch_id IS NULL)条目补 batchId;幂等:
52
+ * 档案内已有任何批次号时收敛到既有批次(按 item_index 最早一条),
53
+ * 没有则生成新批次。返回该 archive 条目所属的 batchId。
54
+ */
55
+ export function assignBatch(store, archiveId) {
56
+ store.archives.requireById(archiveId); // 不存在 → E_NOT_FOUND
57
+ return store.db.transaction(() => {
58
+ const row = store.db.get('SELECT batch_id FROM import_item WHERE archive_id = ? AND batch_id IS NOT NULL ORDER BY item_index LIMIT 1', archiveId);
59
+ const batchId = row != null && row['batch_id'] != null ? String(row['batch_id']) : uuidv7();
60
+ store.db.run('UPDATE import_item SET batch_id = ? WHERE archive_id = ? AND batch_id IS NULL', batchId, archiveId);
61
+ return batchId;
62
+ });
63
+ }
64
+ /** 批次进度:按 import_item.scan_state 与晋升审计标记(审计即状态)统计。 */
65
+ export function batchProgress(store, batchId) {
66
+ const where = 'FROM import_item i WHERE i.batch_id = ?';
67
+ const total = toCount(store.db.scalar(`SELECT COUNT(*) ${where}`, batchId));
68
+ const clean = toCount(store.db.scalar(`SELECT COUNT(*) ${where} AND i.scan_state = 'clean'`, batchId));
69
+ const blocked = toCount(store.db.scalar(`SELECT COUNT(*) ${where} AND i.scan_state = 'blocked'`, batchId));
70
+ const promoted = toCount(store.db.scalar(`SELECT COUNT(*) ${where} AND ${PROMOTED_EXISTS}`, batchId));
71
+ const skipped = toCount(store.db.scalar(`SELECT COUNT(*) ${where} AND ${SKIPPED_EXISTS}`, batchId));
72
+ // remaining = 既未晋升、也未跳过。用 handled 谓词而不是"未晋升",
73
+ // 否则判过 skip 的条目会永远留在待处理队列里(本次变更要修的缺陷)。
74
+ const remaining = toCount(store.db.scalar(`SELECT COUNT(*) ${where} AND i.scan_state = 'clean' AND ${HANDLED_NOT_EXISTS}`, batchId));
75
+ return { batchId, total, clean, blocked, promoted, skipped, remaining };
76
+ }
77
+ /**
78
+ * 下一批待处理切片:scan_state='clean' 且尚未晋升的条目,有界 limit,
79
+ * 供当前 Agent 生成建议。已晋升的条目永不再返回——这就是会话中断续跑的
80
+ * 持久化游标。blocked 条目(秘密/注入命中)在任何情况下都不会进入批次。
81
+ */
82
+ export function nextBatchChunk(store, batchId, limit) {
83
+ if (!Number.isInteger(limit) || limit <= 0) {
84
+ throw err('E_VALIDATION', 'limit 必须是正整数');
85
+ }
86
+ const rows = store.db.all(`SELECT i.id AS id, i.archive_id AS archive_id, i.content AS content,
87
+ i.source_ref AS source_ref, i.content_hash AS content_hash
88
+ FROM import_item i
89
+ WHERE i.batch_id = ? AND i.scan_state = 'clean' AND ${HANDLED_NOT_EXISTS}
90
+ ORDER BY i.archive_id, i.item_index
91
+ LIMIT ?`, batchId, limit);
92
+ return rows.map((r) => ({
93
+ itemId: String(r['id']),
94
+ archiveId: String(r['archive_id']),
95
+ content: String(r['content']),
96
+ sourceRef: r['source_ref'] ?? null,
97
+ contentHash: String(r['content_hash']),
98
+ }));
99
+ }
100
+ /**
101
+ * 晋升标记:真实批准并晋升为正式记忆后调用。写 audit_event
102
+ * (category='onboarding', action='item_promoted',detail 含 itemId+memoryId)。
103
+ * 幂等:同一 (itemId, memoryId) 重复标记不产生第二条审计;同一 itemId 晋升到
104
+ * 不同 memoryId 视为状态改写,抛 E_CONFLICT_STATE。
105
+ *
106
+ * 例外:原目标记忆已被遗忘(tombstone)时允许改挂到新记忆。撤销(policy revoke)
107
+ * 之后再整理必然会走到这里——旧记忆已经不存在,再死守旧映射只会让条目永远卡在
108
+ * "已晋升"。此时追加一条审计,旧的保留在历史里(审计只增不改),判定以新的一条为准。
109
+ *
110
+ * 调用方契约:只允许对 scan_state='clean' 的条目调用(blocked 条目已被
111
+ * nextBatchChunk 排除在批次之外,活动记忆侧另有 DB 触发器兜底)。
112
+ */
113
+ export function markItemPromoted(store, itemId, memoryId) {
114
+ store.archives.requireItem(itemId); // 不存在 → E_NOT_FOUND
115
+ if (typeof memoryId !== 'string' || memoryId.trim().length === 0) {
116
+ throw err('E_VALIDATION', 'markItemPromoted 需要 memoryId');
117
+ }
118
+ store.db.transaction(() => {
119
+ const rows = store.db.all("SELECT detail FROM audit_event WHERE category = ? AND action = ? AND json_extract(detail, '$.itemId') = ?", PROMOTED_CATEGORY, PROMOTED_ACTION, itemId);
120
+ if (rows.length > 0) {
121
+ const prevMemoryId = extractMemoryId(rows[0]['detail']);
122
+ if (prevMemoryId === memoryId)
123
+ return; // 幂等:同条目同记忆,不重复记审计
124
+ if (prevMemoryId == null || !isTombstoned(store, prevMemoryId)) {
125
+ throw err('E_CONFLICT_STATE', '条目已晋升到另一条记忆,拒绝重复标记(审计即状态,不允许改写)', {
126
+ itemId,
127
+ promotedMemoryId: prevMemoryId,
128
+ });
129
+ }
130
+ // 原目标已被遗忘 → 视为重新整理,落到下面的追加逻辑。
131
+ }
132
+ store.audit.record(PROMOTED_CATEGORY, PROMOTED_ACTION, { type: 'import_item', id: itemId }, { itemId, memoryId });
133
+ });
134
+ }
135
+ /**
136
+ * 原晋升目标是否已被遗忘。只认明确的 tombstone:记忆行不存在(脏 id、被硬删的旧数据)
137
+ * 不算"已遗忘",那种情况下宁可报冲突让人看一眼,也不要猜。
138
+ */
139
+ function isTombstoned(store, memoryId) {
140
+ const row = store.db.get('SELECT status FROM memory WHERE id = ?', memoryId);
141
+ return row != null && String(row['status']) === 'tombstoned';
142
+ }
143
+ function extractMemoryId(detail) {
144
+ try {
145
+ const parsed = JSON.parse(String(detail));
146
+ return typeof parsed.memoryId === 'string' ? parsed.memoryId : undefined;
147
+ }
148
+ catch {
149
+ return undefined;
150
+ }
151
+ }
152
+ /** 详情里允许出现的依据类别(用于校验外部传入)。 */
153
+ const SKIP_BASIS = ['rule', 'judgement', 'decision'];
154
+ /**
155
+ * 跳过标记:判定某条导入条目不采用时调用。
156
+ *
157
+ * 写 audit_event(category='onboarding', action='item_skipped',
158
+ * detail 含 itemId/basis/reasonCode)。**detail 不含正文**——审计不是内容存储,
159
+ * 正文可能含敏感内容,理由原文留在复核记录里按 itemId 关联。
160
+ *
161
+ * 幂等:同一 (itemId, basis) 重复标记不产生第二条审计。
162
+ * blocked 条目拒绝标记(它们根本没有进入待处理队列的资格)。
163
+ */
164
+ export function markItemSkipped(store, itemId, input) {
165
+ const item = store.archives.requireItem(itemId); // 不存在 → E_NOT_FOUND
166
+ if (item.scanState === 'blocked') {
167
+ throw err('E_VALIDATION', 'blocked 条目不得记录跳过事实(它们本就不在待处理队列中)', { itemId });
168
+ }
169
+ if (!SKIP_BASIS.includes(input.basis)) {
170
+ throw err('E_VALIDATION', `非法的跳过依据类别: ${JSON.stringify(input.basis)}(支持:${SKIP_BASIS.join(', ')})`);
171
+ }
172
+ const detail = { itemId, basis: input.basis };
173
+ if (typeof input.reasonCode === 'string' && input.reasonCode.length > 0) {
174
+ detail['reasonCode'] = input.reasonCode.slice(0, 120);
175
+ }
176
+ store.db.transaction(() => {
177
+ const rows = store.db.all("SELECT detail FROM audit_event WHERE category = ? AND action = ? AND json_extract(detail, '$.itemId') = ?", PROMOTED_CATEGORY, SKIPPED_ACTION, itemId);
178
+ // 幂等:同条目已用同一依据跳过过,不重复记。
179
+ for (const row of rows) {
180
+ try {
181
+ const prev = JSON.parse(String(row['detail']));
182
+ if (prev.basis === input.basis)
183
+ return;
184
+ }
185
+ catch {
186
+ // 旧数据损坏时按「未记过」处理,继续追加,不吞掉本次判定。
187
+ }
188
+ }
189
+ store.audit.record(PROMOTED_CATEGORY, SKIPPED_ACTION, { type: 'import_item', id: itemId }, detail);
190
+ });
191
+ }
192
+ /**
193
+ * 某批次的已跳过条目。
194
+ *
195
+ * 跳过的条目要从待处理队列出队,但不能从视野里消失——这正是本次变更的取舍:
196
+ * remaining 只数真正待处理的,已跳过的另给一个可查入口。
197
+ */
198
+ export function listSkippedItems(store, batchId, limit = 200) {
199
+ if (!Number.isInteger(limit) || limit <= 0) {
200
+ throw err('E_VALIDATION', 'limit 必须是正整数');
201
+ }
202
+ const rows = store.db.all(`SELECT i.id AS id, json_extract(a.detail, '$.basis') AS basis,
203
+ json_extract(a.detail, '$.reasonCode') AS reason_code, a.at AS at
204
+ FROM audit_event a
205
+ JOIN import_item i ON json_extract(a.detail, '$.itemId') = i.id
206
+ WHERE a.category = ? AND a.action = ? AND i.batch_id = ?
207
+ ORDER BY a.at DESC, i.item_index
208
+ LIMIT ?`, PROMOTED_CATEGORY, SKIPPED_ACTION, batchId, limit);
209
+ return rows.map((r) => ({
210
+ itemId: String(r['id']),
211
+ basis: String(r['basis'] ?? 'unknown'),
212
+ reasonCode: r['reason_code'] ?? null,
213
+ at: String(r['at']),
214
+ }));
215
+ }
216
+ function toCount(v) {
217
+ return Number(v ?? 0);
218
+ }
219
+ //# sourceMappingURL=batches.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"batches.js","sourceRoot":"","sources":["../../../src/onboarding/batches.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,54 @@
1
+ /**
2
+ * 元数据发现适配器(tasks 4.1;agent-onboarding spec「元数据发现与显式选择」)。
3
+ *
4
+ * 硬性边界(spec:发现阶段 MUST 只返回类型、路径、大小等元数据):
5
+ * - 全程只使用 lstat / readdir 获取元数据,绝不 read/open 任何文件内容;
6
+ * 正文读取只发生在用户显式勾选之后的快照层。
7
+ * - 符号链接只判定、不跟随:lstat 判定为符号链接即跳过并记入 skippedNotes,
8
+ * 防止借链接越出白名单范围。
9
+ * - 候选来源仅来自固定白名单相对路径;不递归扫描 homeDir 全盘,
10
+ * 不访问 AppData/Documents 等其他位置,不发起任何网络访问。
11
+ * - 网络路径(UNC,`\\` 或 `//` 前缀)直接抛 E_FORBIDDEN。
12
+ * - 逐文件上限 maxFileBytes(默认 10 MiB):超限文件不列入正文候选,
13
+ * 只记 skippedNotes(oversized);总文件数上限 maxFiles(默认 500)
14
+ * 先到先停,并在受影响候选上注明。
15
+ * - 结果按 (agentKind, path) 排序,同一文件系统状态下输出确定。
16
+ */
17
+ /** 已识别的 Agent 宿主类型。 */
18
+ export type AgentKind = 'claude-code' | 'cursor' | 'copilot' | 'openclaw' | 'workbuddy';
19
+ /** 来源类别:memory = Agent 记忆正文来源;rules = 指令/规则文件来源。 */
20
+ export type SourceKind = 'memory' | 'rules';
21
+ /** 单个候选来源的解析器标识(快照层据此选择解析方式)。 */
22
+ export type SourceParser = 'markdown-memory-index' | 'markdown-topics' | 'markdown-daily' | 'markdown-user-profile' | 'mdc-rules' | 'markdown-instructions' | 'markdown-workspace' | 'markdown-export';
23
+ export interface SourceCandidate {
24
+ agentKind: AgentKind;
25
+ sourceKind: SourceKind;
26
+ /** 绝对路径;目录类来源 = 聚合目录本身。 */
27
+ path: string;
28
+ /** 已列入候选的文件字节总数;被跳过的文件不计入。 */
29
+ byteSize: number;
30
+ /** 目录类来源 = 内部列入的文件数;单文件来源 = 1;被跳过(符号链接/超限)时为 0,仅携带 skippedNotes。 */
31
+ fileCount: number;
32
+ parser: SourceParser;
33
+ /** 能力边界说明(公开路径依据、fixture-only / 手动导出等),中文字符串。 */
34
+ capabilityNote: string;
35
+ /** 因符号链接、超限、文件数上限等原因被跳过的子项说明;无跳过时省略。 */
36
+ skippedNotes?: string[];
37
+ }
38
+ export interface DiscoverOptions {
39
+ /** 合成 HOME:用于 ~/.claude、~/.cursor、~/.openclaw、~/.workbuddy 等 home 级来源。 */
40
+ homeDir: string;
41
+ /** 项目根列表:用于 .github/copilot 指令、AGENTS.md 与项目根 .cursor/rules;homeDir 本身不会自动当作项目根。 */
42
+ projectRoots?: string[];
43
+ /** 全局文件数上限(先到先停)。默认 500。 */
44
+ maxFiles?: number;
45
+ /** 单文件字节上限。默认 10 MiB。 */
46
+ maxFileBytes?: number;
47
+ }
48
+ export declare const DEFAULT_MAX_FILES = 500;
49
+ export declare const DEFAULT_MAX_FILE_BYTES: number;
50
+ /**
51
+ * 元数据发现:列出可识别的 Agent 记忆与规则来源候选。
52
+ * 只返回元数据;正文读取计数为零;不修改任何来源文件。
53
+ */
54
+ export declare function discoverSources(opts: DiscoverOptions): Promise<SourceCandidate[]>;
@@ -0,0 +1,369 @@
1
+ /**
2
+ * 元数据发现适配器(tasks 4.1;agent-onboarding spec「元数据发现与显式选择」)。
3
+ *
4
+ * 硬性边界(spec:发现阶段 MUST 只返回类型、路径、大小等元数据):
5
+ * - 全程只使用 lstat / readdir 获取元数据,绝不 read/open 任何文件内容;
6
+ * 正文读取只发生在用户显式勾选之后的快照层。
7
+ * - 符号链接只判定、不跟随:lstat 判定为符号链接即跳过并记入 skippedNotes,
8
+ * 防止借链接越出白名单范围。
9
+ * - 候选来源仅来自固定白名单相对路径;不递归扫描 homeDir 全盘,
10
+ * 不访问 AppData/Documents 等其他位置,不发起任何网络访问。
11
+ * - 网络路径(UNC,`\\` 或 `//` 前缀)直接抛 E_FORBIDDEN。
12
+ * - 逐文件上限 maxFileBytes(默认 10 MiB):超限文件不列入正文候选,
13
+ * 只记 skippedNotes(oversized);总文件数上限 maxFiles(默认 500)
14
+ * 先到先停,并在受影响候选上注明。
15
+ * - 结果按 (agentKind, path) 排序,同一文件系统状态下输出确定。
16
+ */
17
+ import { lstat, readdir } from 'node:fs/promises';
18
+ import path from 'node:path';
19
+ import { err } from '../core/errors.js';
20
+ export const DEFAULT_MAX_FILES = 500;
21
+ export const DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024;
22
+ // ---------------------------------------------------------------------------
23
+ // 能力边界说明(capabilityNote)
24
+ // ---------------------------------------------------------------------------
25
+ const NOTE_CC_INDEX = 'Claude Code 项目记忆索引(公开路径 ~/.claude/projects/*/memory/MEMORY.md);正文仅在用户显式勾选后由快照层读取';
26
+ const NOTE_CC_TOPICS = 'Claude Code 项目记忆主题文件(与 MEMORY.md 同目录聚合,仅顶层 .md);正文仅在用户显式勾选后由快照层读取';
27
+ const NOTE_CURSOR_RULES = 'Cursor 规则文件(公开路径 ~/.cursor/rules 与项目根 .cursor/rules;仅顶层 .mdc,子目录不展开)';
28
+ const NOTE_COPILOT_SINGLE = 'GitHub Copilot 自定义指令(公开路径 .github/copilot-instructions.md;仅项目根层)';
29
+ const NOTE_COPILOT_DIR = 'GitHub Copilot 按文件类型指令目录(.github/instructions/*.instructions.md;仅顶层匹配文件)';
30
+ const NOTE_AGENTS_MD = '跨 Agent 工作区规则标准(AGENTS.md;Cursor、Copilot 等宿主均读取,此处归入项目根规则来源);仅项目根顶层文件,不解析嵌套目录';
31
+ const NOTE_OPENCLAW_USER = 'OpenClaw 工作区用户画像(公开工作区路径 ~/.openclaw/workspace/USER.md)';
32
+ const NOTE_OPENCLAW_MEMORY = 'OpenClaw 工作区记忆索引(~/.openclaw/workspace/MEMORY.md)';
33
+ const NOTE_OPENCLAW_DAILY = 'OpenClaw 每日记忆目录(~/.openclaw/workspace/memory/*.md;仅顶层 .md)';
34
+ const NOTE_WORKBUDDY = 'WorkBuddy 手动导出的记忆存档(~/.workbuddy/exports/memory-export.md,需用户先在宿主内手动导出);MCP 配置路径官方未公开,不列入记忆来源';
35
+ /**
36
+ * lstat 检查单个路径。发现是非致命的元数据扫描:任何 fs 错误
37
+ * (不存在、无权限、竞态消失等)一律视为 absent,静默不产生来源;
38
+ * 只有 UNC 网络路径这类明确禁止的输入才抛 E_FORBIDDEN。
39
+ */
40
+ async function inspectFile(filePath) {
41
+ let st;
42
+ try {
43
+ st = await lstat(filePath);
44
+ }
45
+ catch {
46
+ return { type: 'absent', size: 0 };
47
+ }
48
+ if (st.isSymbolicLink())
49
+ return { type: 'symlink', size: 0 };
50
+ if (st.isFile())
51
+ return { type: 'file', size: st.size };
52
+ return { type: 'other', size: 0 };
53
+ }
54
+ /** lstat 检查目录(符号链接不视为目录,因此不会被跟随)。 */
55
+ async function dirTypeOf(dirPath) {
56
+ try {
57
+ return (await lstat(dirPath)).isDirectory() ? 'directory' : 'other';
58
+ }
59
+ catch {
60
+ return 'absent';
61
+ }
62
+ }
63
+ /** 列出目录条目名并排序(确定性);目录不可读时视为空。 */
64
+ async function listNames(dirPath) {
65
+ try {
66
+ return (await readdir(dirPath)).sort();
67
+ }
68
+ catch {
69
+ return [];
70
+ }
71
+ }
72
+ function symlinkNote(p) {
73
+ return `symlink: 跳过符号链接 ${p}(发现阶段不跟随链接,防止越界访问)`;
74
+ }
75
+ function oversizedNote(p, size, max) {
76
+ return `oversized: 跳过超限文件 ${p}(${size} 字节超过单文件上限 ${max} 字节),不列入正文快照候选`;
77
+ }
78
+ // ---------------------------------------------------------------------------
79
+ // 白名单相对路径与名称匹配
80
+ // ---------------------------------------------------------------------------
81
+ const isMdName = (n) => n.endsWith('.md');
82
+ const isMdcName = (n) => n.endsWith('.mdc');
83
+ const isInstructionsName = (n) => n.endsWith('.instructions.md');
84
+ // ---------------------------------------------------------------------------
85
+ // 扫描状态:预算与候选收集
86
+ // ---------------------------------------------------------------------------
87
+ class ScanState {
88
+ out = [];
89
+ maxFiles;
90
+ maxFileBytes;
91
+ remaining;
92
+ /** 因预算耗尽而跳过后续计划位置时置位,收尾时补一条全局停止说明。 */
93
+ stopAfterBudget = false;
94
+ constructor(maxFiles, maxFileBytes) {
95
+ this.maxFiles = maxFiles;
96
+ this.maxFileBytes = maxFileBytes;
97
+ this.remaining = maxFiles;
98
+ }
99
+ get open() {
100
+ return this.remaining > 0;
101
+ }
102
+ markStop() {
103
+ if (this.remaining === 0)
104
+ this.stopAfterBudget = true;
105
+ }
106
+ async addSingle(spec) {
107
+ if (!this.open) {
108
+ // 预算耗尽:只做存在性检查;仅当该位置确有可列内容时才记为提前停止,
109
+ // 避免对本来就不存在的来源产生误报说明。
110
+ const ins = await inspectFile(spec.filePath);
111
+ if (ins.type === 'file' || ins.type === 'symlink')
112
+ this.markStop();
113
+ return;
114
+ }
115
+ const ins = await inspectFile(spec.filePath);
116
+ if (ins.type === 'symlink') {
117
+ // 单文件来源本身是符号链接:不产生可快照来源,只保留跳过说明(fileCount = 0)。
118
+ this.push(spec, spec.filePath, [], [symlinkNote(spec.filePath)]);
119
+ return;
120
+ }
121
+ if (ins.type !== 'file')
122
+ return; // absent / 目录 / 其他:静默不产生来源
123
+ if (ins.size > this.maxFileBytes) {
124
+ this.push(spec, spec.filePath, [], [oversizedNote(spec.filePath, ins.size, this.maxFileBytes)]);
125
+ return;
126
+ }
127
+ this.remaining -= 1;
128
+ this.push(spec, spec.filePath, [{ path: spec.filePath, size: ins.size }], []);
129
+ }
130
+ async addDir(spec) {
131
+ if (!this.open) {
132
+ // 预算耗尽:只做存在性检查,目录确有匹配条目才记为提前停止。
133
+ if ((await dirTypeOf(spec.dirPath)) === 'directory') {
134
+ const names = await listNames(spec.dirPath);
135
+ if (names.some((n) => spec.match(n)))
136
+ this.markStop();
137
+ }
138
+ return;
139
+ }
140
+ if ((await dirTypeOf(spec.dirPath)) !== 'directory')
141
+ return;
142
+ const names = await listNames(spec.dirPath);
143
+ const files = [];
144
+ const notes = [];
145
+ let truncated = 0;
146
+ for (const name of names) {
147
+ if (!spec.match(name))
148
+ continue;
149
+ const filePath = path.join(spec.dirPath, name);
150
+ const ins = await inspectFile(filePath);
151
+ if (ins.type === 'absent' || ins.type === 'other')
152
+ continue; // 竞态消失或非常规文件:静默
153
+ if (ins.type === 'symlink') {
154
+ notes.push(symlinkNote(filePath));
155
+ continue;
156
+ }
157
+ if (ins.size > this.maxFileBytes) {
158
+ notes.push(oversizedNote(filePath, ins.size, this.maxFileBytes));
159
+ continue;
160
+ }
161
+ if (this.remaining <= 0) {
162
+ truncated += 1;
163
+ continue;
164
+ }
165
+ files.push({ path: filePath, size: ins.size });
166
+ this.remaining -= 1;
167
+ }
168
+ if (truncated > 0) {
169
+ notes.push(`maxFiles: 已达全局文件数上限 ${this.maxFiles},目录内剩余 ${truncated} 个候选文件未列入`);
170
+ }
171
+ this.push(spec, spec.dirPath, files, notes);
172
+ }
173
+ /** 预算耗尽导致后续计划位置被跳过时,在最后一个候选上补全局停止说明。 */
174
+ finish() {
175
+ if (!this.stopAfterBudget || this.out.length === 0)
176
+ return;
177
+ const last = this.out[this.out.length - 1];
178
+ const notes = last.skippedNotes ?? (last.skippedNotes = []);
179
+ if (!notes.some((n) => n.startsWith('maxFiles:'))) {
180
+ notes.push(`maxFiles: 已达全局文件数上限 ${this.maxFiles},后续来源位置停止扫描`);
181
+ }
182
+ }
183
+ push(spec, candidatePath, files, notes) {
184
+ if (files.length === 0 && notes.length === 0)
185
+ return;
186
+ this.out.push({
187
+ agentKind: spec.agentKind,
188
+ sourceKind: spec.sourceKind,
189
+ path: candidatePath,
190
+ parser: spec.parser,
191
+ capabilityNote: spec.capabilityNote,
192
+ byteSize: files.reduce((sum, f) => sum + f.size, 0),
193
+ fileCount: files.length,
194
+ ...(notes.length > 0 ? { skippedNotes: notes } : {}),
195
+ });
196
+ }
197
+ }
198
+ // ---------------------------------------------------------------------------
199
+ // 输入校验与路径边界
200
+ // ---------------------------------------------------------------------------
201
+ /** 拒绝网络路径(UNC:`\\` 或 `//` 前缀),返回解析后的绝对本地路径。 */
202
+ function assertLocalPath(raw, label) {
203
+ const resolved = path.resolve(raw);
204
+ for (const candidate of [raw, resolved]) {
205
+ if (candidate.startsWith('\\\\') || candidate.startsWith('//')) {
206
+ throw err('E_FORBIDDEN', `${label} 指向网络路径(UNC),发现阶段禁止访问`, { label });
207
+ }
208
+ }
209
+ return resolved;
210
+ }
211
+ function resolveProjectRoots(projectRoots) {
212
+ if (projectRoots === undefined)
213
+ return [];
214
+ if (!Array.isArray(projectRoots))
215
+ throw err('E_VALIDATION', 'projectRoots 必须是字符串数组');
216
+ const fold = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
217
+ const seen = new Set();
218
+ const out = [];
219
+ for (const raw of projectRoots) {
220
+ if (typeof raw !== 'string' || raw.trim() === '') {
221
+ throw err('E_VALIDATION', 'projectRoots 条目必须是非空字符串路径');
222
+ }
223
+ const resolved = assertLocalPath(raw, 'projectRoot');
224
+ const key = fold(resolved);
225
+ if (seen.has(key))
226
+ continue;
227
+ seen.add(key);
228
+ out.push(resolved);
229
+ }
230
+ return out;
231
+ }
232
+ function compareCandidates(a, b) {
233
+ if (a.agentKind !== b.agentKind)
234
+ return a.agentKind < b.agentKind ? -1 : 1;
235
+ if (a.path !== b.path)
236
+ return a.path < b.path ? -1 : 1;
237
+ return 0;
238
+ }
239
+ // ---------------------------------------------------------------------------
240
+ // 各宿主的白名单枚举(顺序固定 → 输出确定)
241
+ // ---------------------------------------------------------------------------
242
+ /** claude-code:仅 ~/.claude/projects/<各项目目录>/memory/(项目级 CLAUDE.md 与 ~/.claude/CLAUDE.md 首版不扫描)。 */
243
+ async function discoverClaudeCodeHome(home, state) {
244
+ const projectsDir = path.join(home, '.claude', 'projects');
245
+ if ((await dirTypeOf(projectsDir)) !== 'directory')
246
+ return;
247
+ for (const name of await listNames(projectsDir)) {
248
+ const projectDir = path.join(projectsDir, name);
249
+ // 符号链接/文件形式的 project 条目整项静默跳过:无候选可承载说明,且绝不跟随链接。
250
+ if ((await dirTypeOf(projectDir)) !== 'directory')
251
+ continue;
252
+ const memoryDir = path.join(projectDir, 'memory');
253
+ // 预算耗尽时 addSingle/addDir 只做存在性检查;确有内容才记为提前停止。
254
+ await state.addSingle({
255
+ agentKind: 'claude-code',
256
+ sourceKind: 'memory',
257
+ filePath: path.join(memoryDir, 'MEMORY.md'),
258
+ parser: 'markdown-memory-index',
259
+ capabilityNote: NOTE_CC_INDEX,
260
+ });
261
+ await state.addDir({
262
+ agentKind: 'claude-code',
263
+ sourceKind: 'memory',
264
+ dirPath: memoryDir,
265
+ parser: 'markdown-topics',
266
+ capabilityNote: NOTE_CC_TOPICS,
267
+ match: (n) => n.endsWith('.md') && n !== 'MEMORY.md',
268
+ });
269
+ }
270
+ }
271
+ /**
272
+ * 元数据发现:列出可识别的 Agent 记忆与规则来源候选。
273
+ * 只返回元数据;正文读取计数为零;不修改任何来源文件。
274
+ */
275
+ export async function discoverSources(opts) {
276
+ const { homeDir, projectRoots, maxFiles = DEFAULT_MAX_FILES, maxFileBytes = DEFAULT_MAX_FILE_BYTES } = opts ?? {};
277
+ if (typeof homeDir !== 'string' || homeDir.trim() === '') {
278
+ throw err('E_VALIDATION', 'homeDir 必须是非空字符串路径');
279
+ }
280
+ if (!Number.isInteger(maxFiles) || maxFiles < 1) {
281
+ throw err('E_VALIDATION', `maxFiles 必须是正整数,收到 ${String(maxFiles)}`);
282
+ }
283
+ if (!Number.isInteger(maxFileBytes) || maxFileBytes < 1) {
284
+ throw err('E_VALIDATION', `maxFileBytes 必须是正整数,收到 ${String(maxFileBytes)}`);
285
+ }
286
+ // 先完成全部输入校验(含 UNC 拒绝),再做任何文件系统访问。
287
+ const home = assertLocalPath(homeDir, 'homeDir');
288
+ const roots = resolveProjectRoots(projectRoots);
289
+ const state = new ScanState(maxFiles, maxFileBytes);
290
+ // --- home 级来源 ---
291
+ if ((await dirTypeOf(home)) === 'directory') {
292
+ await discoverClaudeCodeHome(home, state);
293
+ await state.addDir({
294
+ agentKind: 'cursor',
295
+ sourceKind: 'rules',
296
+ dirPath: path.join(home, '.cursor', 'rules'),
297
+ parser: 'mdc-rules',
298
+ capabilityNote: NOTE_CURSOR_RULES,
299
+ match: isMdcName,
300
+ });
301
+ await state.addSingle({
302
+ agentKind: 'openclaw',
303
+ sourceKind: 'memory',
304
+ filePath: path.join(home, '.openclaw', 'workspace', 'USER.md'),
305
+ parser: 'markdown-user-profile',
306
+ capabilityNote: NOTE_OPENCLAW_USER,
307
+ });
308
+ await state.addSingle({
309
+ agentKind: 'openclaw',
310
+ sourceKind: 'memory',
311
+ filePath: path.join(home, '.openclaw', 'workspace', 'MEMORY.md'),
312
+ parser: 'markdown-memory-index',
313
+ capabilityNote: NOTE_OPENCLAW_MEMORY,
314
+ });
315
+ await state.addDir({
316
+ agentKind: 'openclaw',
317
+ sourceKind: 'memory',
318
+ dirPath: path.join(home, '.openclaw', 'workspace', 'memory'),
319
+ parser: 'markdown-daily',
320
+ capabilityNote: NOTE_OPENCLAW_DAILY,
321
+ match: isMdName,
322
+ });
323
+ await state.addSingle({
324
+ agentKind: 'workbuddy',
325
+ sourceKind: 'memory',
326
+ filePath: path.join(home, '.workbuddy', 'exports', 'memory-export.md'),
327
+ parser: 'markdown-export',
328
+ capabilityNote: NOTE_WORKBUDDY,
329
+ });
330
+ }
331
+ // --- 项目根级来源(homeDir 不会自动当作项目根;调用方需要时自行传入)---
332
+ for (const root of roots) {
333
+ if ((await dirTypeOf(root)) !== 'directory')
334
+ continue;
335
+ await state.addSingle({
336
+ agentKind: 'copilot',
337
+ sourceKind: 'rules',
338
+ filePath: path.join(root, '.github', 'copilot-instructions.md'),
339
+ parser: 'markdown-instructions',
340
+ capabilityNote: NOTE_COPILOT_SINGLE,
341
+ });
342
+ await state.addDir({
343
+ agentKind: 'copilot',
344
+ sourceKind: 'rules',
345
+ dirPath: path.join(root, '.github', 'instructions'),
346
+ parser: 'markdown-instructions',
347
+ capabilityNote: NOTE_COPILOT_DIR,
348
+ match: isInstructionsName,
349
+ });
350
+ await state.addSingle({
351
+ agentKind: 'copilot',
352
+ sourceKind: 'rules',
353
+ filePath: path.join(root, 'AGENTS.md'),
354
+ parser: 'markdown-workspace',
355
+ capabilityNote: NOTE_AGENTS_MD,
356
+ });
357
+ await state.addDir({
358
+ agentKind: 'cursor',
359
+ sourceKind: 'rules',
360
+ dirPath: path.join(root, '.cursor', 'rules'),
361
+ parser: 'mdc-rules',
362
+ capabilityNote: NOTE_CURSOR_RULES,
363
+ match: isMdcName,
364
+ });
365
+ }
366
+ state.finish();
367
+ return state.out.sort(compareCandidates);
368
+ }
369
+ //# sourceMappingURL=discover.js.map