@adamchanadam/agent-handoff-kit 0.3.32 → 0.3.34
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.
- package/README.md +8 -6
- package/bin/agent-handoff-kit.mjs +132 -48
- package/package.json +31 -20
- package/packs/integrations.md +47 -27
- package/packs/knowledge.md +5 -5
- package/packs/onboarding.md +4 -4
- package/packs/safety.md +5 -5
- package/runtime-core/AGENTS.core.md +1 -1
- package/runtime-core/PROJECT_INDEX.md +5 -5
- package/runtime-core/SESSION_HANDOFF.md +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Handoff Kit
|
|
2
2
|
|
|
3
|
-
狀態:目前版本為 `v0.3.
|
|
3
|
+
狀態:目前版本為 `v0.3.34`。這是早期可用版本,仍在持續完善中。
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
6
|
<img src="https://raw.githubusercontent.com/Adamchanadam/agent-handoff-kit/main/images/agent-handoff-kit-promo-30s.gif" alt="Agent Handoff Kit 功能簡介動畫" width="720">
|
|
@@ -19,7 +19,7 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
|
|
|
19
19
|
1. 在你想使用 Agent Handoff Kit 的資料夾打開 AI,貼上這句話:
|
|
20
20
|
|
|
21
21
|
```text
|
|
22
|
-
請讀取 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html,並在這個資料夾安裝或升級 Agent Handoff Kit。
|
|
22
|
+
請讀取 https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html ,並在這個資料夾安裝或升級 Agent Handoff Kit。
|
|
23
23
|
```
|
|
24
24
|
|
|
25
25
|
你也可以先打開 [`agent-handoff-kit-ai-install.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html) 看看 AI 會照甚麼步驟處理。
|
|
@@ -44,7 +44,9 @@ Agent Handoff Kit 是 **AI 對話之間的接力棒**。
|
|
|
44
44
|
| [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) | 三個實操情景,示範開工、工作、收工。 |
|
|
45
45
|
| [`agent-handoff-kit-ai-install.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-ai-install.html) | 給 AI 讀的安裝與升級指令頁。 |
|
|
46
46
|
|
|
47
|
-
|
|
47
|
+
repo 內的 `scripts/`、`test-fixtures/`、`docs/qa/` 和部分設計文件,是維護者用來測試升級、安全合併和發佈品質的材料。普通用戶不需要閱讀,也不會被 npm 安裝到你的項目;npm package 只包含實際執行需要的核心檔案。
|
|
48
|
+
|
|
49
|
+
維護者請看 [`MAINTAINERS.md`](MAINTAINERS.md)。
|
|
48
50
|
|
|
49
51
|
## 🔎 它解決甚麼問題
|
|
50
52
|
|
|
@@ -145,7 +147,7 @@ AI 會處理檢查,不會把「檢查通過」誤當成已理解你的專案
|
|
|
145
147
|
| 寫文章 / README / 社交帖文 | 先確認讀者、目的、語氣和發布位置。 |
|
|
146
148
|
| 查資料 / 比較工具 | 分清已驗證事實、來源摘要和 AI 推論。 |
|
|
147
149
|
| 刪檔 / Git / 發佈 / npm | 高風險操作必須先說明影響,並等你確認。 |
|
|
148
|
-
| Notion / Google Drive 等外部工具 |
|
|
150
|
+
| Notion / Google Drive 等外部工具 | 先核對目前工具 schema 或官方文件;機密不寫入項目文件。 |
|
|
149
151
|
|
|
150
152
|
你只要用日常話說目的,例如「幫我改 README」、「幫我查這個工具是否適合」、「把這份文件接入 Agent Handoff Kit」。AI 會自己判斷要用哪些規則。
|
|
151
153
|
|
|
@@ -183,7 +185,7 @@ AI 應先判斷這條規則應放在哪裡:是一次性備忘、下次交接
|
|
|
183
185
|
|
|
184
186
|
- 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
|
|
185
187
|
- 機密保護:`.env`、API key、token 不可印出、不可提交、不可上傳。
|
|
186
|
-
-
|
|
188
|
+
- 查證不猜:使用第三方服務、Connector、MCP、CLI、API 或 plugin API 前,先核對目前工具 schema、官方文件或有版本日期的本地 runbook;查不到就標示未核實。
|
|
187
189
|
- 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
|
|
188
190
|
- 發佈需明確批准:建立版本標籤、GitHub Release、npm publish、部署或上傳,都不能因「準備好了」而自動執行。
|
|
189
191
|
|
|
@@ -198,7 +200,7 @@ Agent Handoff Kit 可與 [Adam-AI-Instructions](https://github.com/prompt-templa
|
|
|
198
200
|
|
|
199
201
|
## ⚠️ 目前限制
|
|
200
202
|
|
|
201
|
-
- 目前版本為 `v0.3.
|
|
203
|
+
- 目前版本為 `v0.3.34`;正式安裝請以 npm registry `latest` 顯示為準。
|
|
202
204
|
- 這是早期可用版本,仍在持續完善中。
|
|
203
205
|
- 升級合併屬窄範圍策略,不是完整的複雜合併工具。
|
|
204
206
|
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
@@ -233,12 +233,16 @@ const requiredAnchors = [
|
|
|
233
233
|
"Integrations Pack",
|
|
234
234
|
"Connectors",
|
|
235
235
|
"MCPs",
|
|
236
|
-
"Plugins",
|
|
237
|
-
"Skills",
|
|
238
|
-
"機密分離原則",
|
|
239
|
-
"
|
|
240
|
-
"
|
|
241
|
-
"
|
|
236
|
+
"Plugins",
|
|
237
|
+
"Skills",
|
|
238
|
+
"機密分離原則",
|
|
239
|
+
"External Tool Usage Verification Gate",
|
|
240
|
+
"do not invent",
|
|
241
|
+
"input schema",
|
|
242
|
+
"official documentation",
|
|
243
|
+
"Source-of-truth Architecture",
|
|
244
|
+
"Cross-session Lifecycle",
|
|
245
|
+
"Connector-first default",
|
|
242
246
|
"Anti-pattern"
|
|
243
247
|
]
|
|
244
248
|
}
|
|
@@ -348,8 +352,8 @@ const schemaChecks = [
|
|
|
348
352
|
tableHeader("Check", "Command", "Run before", "Last verified"),
|
|
349
353
|
tableHeader("Change type", "Likely files", "Required checks"),
|
|
350
354
|
// R-030 v0.3.0+: Installed Integrations subsection table headers
|
|
351
|
-
tableHeader("Tool", "Project Usage", "Access Scope", "Specific Instance", "Credential
|
|
352
|
-
tableHeader("Server", "Source", "Project Usage", "Credential
|
|
355
|
+
tableHeader("Tool", "Project Usage", "Access Scope", "Specific Instance", "Credential Reference(no value)", "Declared", "Last Verified"),
|
|
356
|
+
tableHeader("Server", "Source", "Project Usage", "Credential Reference(no value)", "Declared", "Last Verified"),
|
|
353
357
|
tableHeader("Name", "Bundle Content(Skills + MCP + hooks)", "When Triggered", "Last Verified"),
|
|
354
358
|
tableHeader("Name", "Source", "When Triggered", "Last Verified"),
|
|
355
359
|
tableHeader("Layer", "Surface(具體 instance)", "Role", "Write Direction")
|
|
@@ -1739,20 +1743,35 @@ function classifyExistingFile(command, sourceRel, targetRel, sourceAbs, targetAb
|
|
|
1739
1743
|
// ## Local QC Commands on upgrade if missing. NON-DESTRUCTIVE: existing ## External Sources content
|
|
1740
1744
|
// is fully preserved (including any user-filled rows). User can later manually add the `via` column
|
|
1741
1745
|
// to External Sources rows (or AI can guide that incremental migration during a later session).
|
|
1742
|
-
if (targetRel === "dev/PROJECT_INDEX.md" && command === "upgrade" && !targetText.includes("## Installed Integrations")) {
|
|
1743
|
-
// Extract just the ## Installed Integrations block from source (not touching External Sources).
|
|
1744
|
-
const sourceInstalledMatch = sourceText.match(/(## Installed Integrations[\s\S]*?)(?=## Local QC Commands)/);
|
|
1745
|
-
if (sourceInstalledMatch && targetText.includes("## Local QC Commands")) {
|
|
1746
|
+
if (targetRel === "dev/PROJECT_INDEX.md" && command === "upgrade" && !targetText.includes("## Installed Integrations")) {
|
|
1747
|
+
// Extract just the ## Installed Integrations block from source (not touching External Sources).
|
|
1748
|
+
const sourceInstalledMatch = sourceText.match(/(## Installed Integrations[\s\S]*?)(?=## Local QC Commands)/);
|
|
1749
|
+
if (sourceInstalledMatch && targetText.includes("## Local QC Commands")) {
|
|
1746
1750
|
const installedBlock = sourceInstalledMatch[1];
|
|
1747
1751
|
return {
|
|
1748
1752
|
...base,
|
|
1749
1753
|
action: "merge",
|
|
1750
1754
|
reason: "insert ## Installed Integrations section template before ## Local QC Commands (R-030 Integration governance migration; existing External Sources content preserved non-destructively)",
|
|
1751
1755
|
mergedText: targetText.replace("## Local QC Commands", installedBlock + "## Local QC Commands")
|
|
1752
|
-
};
|
|
1753
|
-
}
|
|
1754
|
-
}
|
|
1755
|
-
|
|
1756
|
+
};
|
|
1757
|
+
}
|
|
1758
|
+
}
|
|
1759
|
+
if (targetRel === "dev/PROJECT_INDEX.md" && command === "upgrade" && (
|
|
1760
|
+
targetText.includes("Credential Location")
|
|
1761
|
+
|| targetText.includes("Claude Code MCP config + env var")
|
|
1762
|
+
|| targetText.includes("Credential 應由 AI 工具自身 secure storage 管理(譬如 Claude Desktop Extensions")
|
|
1763
|
+
)) {
|
|
1764
|
+
const mergedProjectIndex = mergeProjectIndexCredentialReferences(targetText);
|
|
1765
|
+
if (mergedProjectIndex !== targetText) {
|
|
1766
|
+
return {
|
|
1767
|
+
...base,
|
|
1768
|
+
action: "merge",
|
|
1769
|
+
reason: "update PROJECT_INDEX credential reference wording without changing user integration rows",
|
|
1770
|
+
mergedText: mergedProjectIndex
|
|
1771
|
+
};
|
|
1772
|
+
}
|
|
1773
|
+
}
|
|
1774
|
+
// R-030 v0.3.0+: dev/rules/onboarding.md gets ### Scenario F block auto-inserted before
|
|
1756
1775
|
// ## Cross-reference to guide.html on upgrade if missing. NON-DESTRUCTIVE: existing Scenarios A-E
|
|
1757
1776
|
// content and any user customization preserved. Step 1 micro-question additions to Scenarios A-E
|
|
1758
1777
|
// are NOT auto-migrated (user-customizable inline sample wording, not anchor-enforced); users get
|
|
@@ -2100,10 +2119,10 @@ function onboardingAnchorPlacement(snippet, text) {
|
|
|
2100
2119
|
return true;
|
|
2101
2120
|
}
|
|
2102
2121
|
|
|
2103
|
-
function integrationsAnchorPlacement(snippet, text) {
|
|
2104
|
-
if (snippet === "機密分離原則" || snippet === "Source-of-truth Architecture" || snippet === "Cross-session Lifecycle") {
|
|
2105
|
-
return snippetAppearsBetweenHeadings(text, snippet, "## Discipline", "## Rules");
|
|
2106
|
-
}
|
|
2122
|
+
function integrationsAnchorPlacement(snippet, text) {
|
|
2123
|
+
if (snippet === "機密分離原則" || snippet === "External Tool Usage Verification Gate" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation" || snippet === "Source-of-truth Architecture" || snippet === "Cross-session Lifecycle") {
|
|
2124
|
+
return snippetAppearsBetweenHeadings(text, snippet, "## Discipline", "## Rules");
|
|
2125
|
+
}
|
|
2107
2126
|
if (snippet === "Connector-first default") {
|
|
2108
2127
|
return snippetAppearsBetweenHeadings(text, snippet, "## Rules", "## Checks");
|
|
2109
2128
|
}
|
|
@@ -2174,14 +2193,14 @@ const semanticAnchorRepairStrategies = {
|
|
|
2174
2193
|
mergedText: mergedSafety
|
|
2175
2194
|
} : null;
|
|
2176
2195
|
},
|
|
2177
|
-
"dev/rules/integrations.md": (targetText, sourceText, missing) => {
|
|
2178
|
-
const mergedIntegrations =
|
|
2179
|
-
return mergedIntegrations ? {
|
|
2180
|
-
action: "merge",
|
|
2181
|
-
reason: "restore integrations credential
|
|
2182
|
-
mergedText: mergedIntegrations
|
|
2183
|
-
} : null;
|
|
2184
|
-
}
|
|
2196
|
+
"dev/rules/integrations.md": (targetText, sourceText, missing) => {
|
|
2197
|
+
const mergedIntegrations = mergeIntegrationsSectionsByMissingAnchors(targetText, sourceText, missing);
|
|
2198
|
+
return mergedIntegrations ? {
|
|
2199
|
+
action: "merge",
|
|
2200
|
+
reason: "restore integrations verification and credential sections in semantic position",
|
|
2201
|
+
mergedText: mergedIntegrations
|
|
2202
|
+
} : null;
|
|
2203
|
+
}
|
|
2185
2204
|
};
|
|
2186
2205
|
|
|
2187
2206
|
function mergeMissingRequiredAnchorsSemantically(targetRel, targetText, sourceText) {
|
|
@@ -2229,10 +2248,10 @@ function mergeProjectDecisionsPreamble(targetText, sourceText, missing) {
|
|
|
2229
2248
|
return insertSourcePreambleBeforeHeading(targetText, sourceText, "## Evolution Timeline");
|
|
2230
2249
|
}
|
|
2231
2250
|
|
|
2232
|
-
function mergeProjectIndexTemplateVersionRow(targetText, sourceText) {
|
|
2233
|
-
if (projectIndexTemplateVersion(targetText)) return targetText;
|
|
2234
|
-
const sourceRow = sourceText.match(/^\| Agent Handoff Kit template version \| [\d.]+ \| [^|\n]+ \|$/m)?.[0];
|
|
2235
|
-
if (!sourceRow) return null;
|
|
2251
|
+
function mergeProjectIndexTemplateVersionRow(targetText, sourceText) {
|
|
2252
|
+
if (projectIndexTemplateVersion(targetText)) return targetText;
|
|
2253
|
+
const sourceRow = sourceText.match(/^\| Agent Handoff Kit template version \| [\d.]+ \| [^|\n]+ \|$/m)?.[0];
|
|
2254
|
+
if (!sourceRow) return null;
|
|
2236
2255
|
const lines = targetText.split(/\r?\n/);
|
|
2237
2256
|
const stackIndex = lines.findIndex((line) => line.trim() === "## Stack");
|
|
2238
2257
|
if (stackIndex < 0) return null;
|
|
@@ -2240,11 +2259,31 @@ function mergeProjectIndexTemplateVersionRow(targetText, sourceText) {
|
|
|
2240
2259
|
if (tableHeaderIndex < 0) return null;
|
|
2241
2260
|
const separatorIndex = tableHeaderIndex + 1;
|
|
2242
2261
|
if (!lines[separatorIndex]?.startsWith("|---")) return null;
|
|
2243
|
-
lines.splice(separatorIndex + 1, 0, sourceRow);
|
|
2244
|
-
return lines.join("\n");
|
|
2245
|
-
}
|
|
2246
|
-
|
|
2247
|
-
function
|
|
2262
|
+
lines.splice(separatorIndex + 1, 0, sourceRow);
|
|
2263
|
+
return lines.join("\n");
|
|
2264
|
+
}
|
|
2265
|
+
|
|
2266
|
+
function mergeProjectIndexCredentialReferences(targetText) {
|
|
2267
|
+
return targetText
|
|
2268
|
+
.replace(
|
|
2269
|
+
"Credential 應由 AI 工具自身 secure storage 管理(譬如 Claude Desktop Extensions 嘅 OS Keychain / Claude Code MCP config)。",
|
|
2270
|
+
"Credential 應由 AI 工具自身 secure storage / OS credential store / tool config / user-managed secret store 管理;若使用 env,只可記錄 env var name,不可讀取、貼出或保存 value。"
|
|
2271
|
+
)
|
|
2272
|
+
.replaceAll(
|
|
2273
|
+
"Credential Location",
|
|
2274
|
+
"Credential Reference(no value)"
|
|
2275
|
+
)
|
|
2276
|
+
.replace(
|
|
2277
|
+
"`Claude Desktop Extensions`",
|
|
2278
|
+
"`AI tool secure storage` / `OS credential store`"
|
|
2279
|
+
)
|
|
2280
|
+
.replace(
|
|
2281
|
+
"`Claude Code MCP config + env var`",
|
|
2282
|
+
"`tool config + env var name only` / `user-managed secret store`"
|
|
2283
|
+
);
|
|
2284
|
+
}
|
|
2285
|
+
|
|
2286
|
+
function mergeSafetyRulesByMissingAnchors(targetText, sourceText, missing) {
|
|
2248
2287
|
if (!hasTrustedSafetyPackShape(targetText)) return null;
|
|
2249
2288
|
const targetBounds = sectionBounds(targetText, "## Rules", "## Checks");
|
|
2250
2289
|
const sourceBounds = sectionBounds(sourceText, "## Rules", "## Checks");
|
|
@@ -2280,17 +2319,62 @@ function mergeSafetyRulesByMissingAnchors(targetText, sourceText, missing) {
|
|
|
2280
2319
|
return changed ? targetLines.join("\n") : targetText;
|
|
2281
2320
|
}
|
|
2282
2321
|
|
|
2283
|
-
function
|
|
2284
|
-
|
|
2285
|
-
|
|
2286
|
-
|
|
2287
|
-
|
|
2288
|
-
|
|
2289
|
-
|
|
2290
|
-
|
|
2291
|
-
|
|
2292
|
-
|
|
2293
|
-
|
|
2322
|
+
function mergeIntegrationsSectionsByMissingAnchors(targetText, sourceText, missing) {
|
|
2323
|
+
let merged = targetText;
|
|
2324
|
+
let changed = false;
|
|
2325
|
+
|
|
2326
|
+
if (missing.some((snippet) => snippet === "機密分離原則")) {
|
|
2327
|
+
const withCredential = replaceSectionByHeadingWithinBounds(
|
|
2328
|
+
merged,
|
|
2329
|
+
sourceText,
|
|
2330
|
+
/^### 1\. (機密分離原則|credential-separation anchor removed from this stale local copy)/m,
|
|
2331
|
+
/^### 2\. /m,
|
|
2332
|
+
"## Discipline",
|
|
2333
|
+
"## Rules"
|
|
2334
|
+
);
|
|
2335
|
+
if (!withCredential) return null;
|
|
2336
|
+
merged = withCredential;
|
|
2337
|
+
changed = true;
|
|
2338
|
+
}
|
|
2339
|
+
|
|
2340
|
+
if (missing.some((snippet) => snippet === "External Tool Usage Verification Gate" || snippet === "do not invent" || snippet === "input schema" || snippet === "official documentation")) {
|
|
2341
|
+
const withVerificationGate = mergeIntegrationsVerificationGateSection(merged, sourceText);
|
|
2342
|
+
if (!withVerificationGate) return null;
|
|
2343
|
+
merged = withVerificationGate;
|
|
2344
|
+
changed = true;
|
|
2345
|
+
}
|
|
2346
|
+
|
|
2347
|
+
return changed ? merged : null;
|
|
2348
|
+
}
|
|
2349
|
+
|
|
2350
|
+
function mergeIntegrationsVerificationGateSection(targetText, sourceText) {
|
|
2351
|
+
if (countText(targetText, "## Discipline") !== 1 || countText(targetText, "## Rules") !== 1) return null;
|
|
2352
|
+
const targetBounds = textSectionBounds(targetText, "## Discipline", "## Rules");
|
|
2353
|
+
const sourceBounds = textSectionBounds(sourceText, "## Discipline", "## Rules");
|
|
2354
|
+
if (!targetBounds || !sourceBounds) return null;
|
|
2355
|
+
|
|
2356
|
+
const boundedTarget = targetText.slice(targetBounds.start, targetBounds.end);
|
|
2357
|
+
const boundedSource = sourceText.slice(sourceBounds.start, sourceBounds.end);
|
|
2358
|
+
const sourceSection = extractSection(boundedSource, /^### 2\. External Tool Usage Verification Gate/m, /^### 3\. /m);
|
|
2359
|
+
if (!sourceSection) return null;
|
|
2360
|
+
|
|
2361
|
+
const existingTargetSection = extractSection(boundedTarget, /^### 2\. External Tool Usage Verification Gate/m, /^### 3\. /m);
|
|
2362
|
+
if (existingTargetSection) {
|
|
2363
|
+
return `${targetText.slice(0, targetBounds.start + existingTargetSection.start)}${sourceSection.text}${targetText.slice(targetBounds.start + existingTargetSection.end)}`;
|
|
2364
|
+
}
|
|
2365
|
+
|
|
2366
|
+
const oldFourTypesHeading = /^### 2\. 四類整合嘅紀律差異/m.exec(boundedTarget);
|
|
2367
|
+
if (oldFourTypesHeading) {
|
|
2368
|
+
return `${targetText.slice(0, targetBounds.start + oldFourTypesHeading.index)}${sourceSection.text}${targetText.slice(targetBounds.start + oldFourTypesHeading.index)}`;
|
|
2369
|
+
}
|
|
2370
|
+
|
|
2371
|
+
const currentFourTypesHeading = /^### 3\. 四類整合嘅紀律差異/m.exec(boundedTarget);
|
|
2372
|
+
if (currentFourTypesHeading) {
|
|
2373
|
+
return `${targetText.slice(0, targetBounds.start + currentFourTypesHeading.index)}${sourceSection.text}${targetText.slice(targetBounds.start + currentFourTypesHeading.index)}`;
|
|
2374
|
+
}
|
|
2375
|
+
|
|
2376
|
+
return null;
|
|
2377
|
+
}
|
|
2294
2378
|
|
|
2295
2379
|
function hasTrustedSafetyPackShape(text) {
|
|
2296
2380
|
return text.includes("# Safety Pack")
|
package/package.json
CHANGED
|
@@ -1,20 +1,31 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
-
"version": "0.3.
|
|
4
|
-
"description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"bin": {
|
|
7
|
-
"agent-handoff-kit": "bin/agent-handoff-kit.mjs"
|
|
8
|
-
},
|
|
9
|
-
"files": [
|
|
10
|
-
"bin/",
|
|
11
|
-
"runtime-core/",
|
|
12
|
-
"packs/",
|
|
13
|
-
"README.md",
|
|
14
|
-
"LICENSE"
|
|
15
|
-
],
|
|
16
|
-
"
|
|
17
|
-
"
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "@adamchanadam/agent-handoff-kit",
|
|
3
|
+
"version": "0.3.34",
|
|
4
|
+
"description": "Lightweight agent harness for project memory, handoff, and multi-session continuity.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"agent-handoff-kit": "bin/agent-handoff-kit.mjs"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"bin/",
|
|
11
|
+
"runtime-core/",
|
|
12
|
+
"packs/",
|
|
13
|
+
"README.md",
|
|
14
|
+
"LICENSE"
|
|
15
|
+
],
|
|
16
|
+
"scripts": {
|
|
17
|
+
"doctor": "node bin/agent-handoff-kit.mjs doctor --root .",
|
|
18
|
+
"dry-run": "node bin/agent-handoff-kit.mjs init --dry-run --root .",
|
|
19
|
+
"qa:prototype": "node scripts/check-public-prototype.mjs",
|
|
20
|
+
"qa:public-mirror": "node scripts/build-public-mirror.mjs",
|
|
21
|
+
"qa:packs": "node scripts/check-pack-scenarios.mjs",
|
|
22
|
+
"qa:upgrade": "node scripts/check-upgrade-safety.mjs",
|
|
23
|
+
"qa:release": "node scripts/check-release-readiness.mjs",
|
|
24
|
+
"qa:prompt-mirror": "node scripts/check-prompt-mirror.mjs",
|
|
25
|
+
"qa:fixtures": "node scripts/generate-upgrade-fixtures.mjs"
|
|
26
|
+
},
|
|
27
|
+
"engines": {
|
|
28
|
+
"node": ">=18"
|
|
29
|
+
},
|
|
30
|
+
"license": "MIT"
|
|
31
|
+
}
|
package/packs/integrations.md
CHANGED
|
@@ -20,13 +20,14 @@
|
|
|
20
20
|
|
|
21
21
|
### 1. 機密分離原則(最高優先)
|
|
22
22
|
|
|
23
|
-
**Credential(API key / OAuth token / app secret / refresh token)由 AI 工具自身 secure storage 管理**,與本 Kit 完全分離:
|
|
23
|
+
**Credential(API key / OAuth token / app secret / refresh token)由 AI 工具自身 secure storage、OS credential store、tool config、或用戶自管 secret store 管理**,與本 Kit 完全分離:
|
|
24
24
|
|
|
25
|
-
| 儲存層 | 例子 |
|
|
25
|
+
| 儲存層 | 例子 | Kit 可記錄內容 |
|
|
26
26
|
|--------|------|----------|
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
| 其他 AI tool
|
|
27
|
+
| AI tool secure storage / Connector storage | Notion / Slack / Linear / Google Drive / Atlassian 等 | 只記 `AI tool secure storage` 或 connector 名稱,不記 value |
|
|
28
|
+
| OS credential store | macOS Keychain / Windows Credential Manager / Linux secret service 等 | 只記 `OS credential store`,不讀取、不導出 value |
|
|
29
|
+
| Tool config / env indirection | Claude Code MCP config / 其他 AI tool config / env var | 只記 config 位置或 env var name;不可讀取、貼出、保存 env value |
|
|
30
|
+
| User-managed secret store | 由用戶或團隊管理嘅 vault / secret manager | 只記 store 類型或 owner,具體 secret value 由用戶管理 |
|
|
30
31
|
|
|
31
32
|
Kit 嘅 `dev/` folder **任何檔都不 touch credential value**。三條硬性 enforcement:
|
|
32
33
|
|
|
@@ -34,27 +35,41 @@ Kit 嘅 `dev/` folder **任何檔都不 touch credential value**。三條硬性
|
|
|
34
35
|
2. AI 識別到 credential prefix(`sk-` / `sk-ant-` / `ntn_` / `secret_` / `ya29.` / `1//` / `xoxp-` / `xoxb-` / `ghp_` / `gho_` / `ghs_` / `github_pat_` / `sl.` / `AKIA` / `AIza` 等)會即時 redact + warn 用戶 rotate token
|
|
35
36
|
3. 寫入 `dev/PROJECT_INDEX.md` `## Installed Integrations` 前 self-check 確認無 credential leak;doctor `checkInstalledIntegrationsCredentialLeak()` 對 PROJECT_INDEX + SESSION_HANDOFF + SESSION_LOG 三個 surface 強制 grep
|
|
36
37
|
|
|
37
|
-
### 2.
|
|
38
|
+
### 2. External Tool Usage Verification Gate
|
|
38
39
|
|
|
39
|
-
|
|
40
|
+
AI must not use model memory, old session experience, copied examples, Connector marketing text, or guessed command shapes as the source for external-tool usage. Before first use of an external tool layer in the current task, and again before any write, destructive action, permission-sensitive action, raw API / SDK / CLI / URI call, plugin API change, or retry after `unknown tool`, `invalid arguments`, HTTP 400 / 404, permission, auth, or schema errors, verify the current usage source for that layer:
|
|
40
41
|
|
|
41
|
-
|
|
42
|
+
| Layer | Required current source before invocation |
|
|
43
|
+
|---|---|
|
|
44
|
+
| Connector / MCP tool | Current runtime-exposed tool name, description, and input schema. Use the tool list/schema exposed by the active AI runtime or MCP server; do not invent `mcp__*` names or arguments. |
|
|
45
|
+
| Plugin / Skill | Current plugin/skill instructions plus any registered MCP tool schema it exposes. |
|
|
46
|
+
| Raw API / SDK / CLI / URI | Current official documentation or a project-local runbook that states source, version/date, and scope. If the runbook lacks those, verify against official docs. |
|
|
47
|
+
| Local app plugin API | Official API documentation, official type definitions, official sample project, or local installed package types matching the project version. |
|
|
48
|
+
| Project-local runbook | Accept as a task source only when it records the upstream source, version/date, scope, and known limits. |
|
|
49
|
+
|
|
50
|
+
If the required source cannot be inspected, mark the tool use `blocked` or `unverified`, ask the user for the current docs/schema/runbook, or fall back to a manual packet. Do not continue by trial and error. Connector-first means schema-first for the active runtime, not memory-first.
|
|
51
|
+
|
|
52
|
+
### 3. 四類整合嘅紀律差異
|
|
53
|
+
|
|
54
|
+
#### 3.1 Connectors(Anthropic 官方 vetted)
|
|
55
|
+
|
|
56
|
+
Anthropic 官方 directory 嘅 ready-to-use MCP server(譬如 Notion / Slack / Linear / Google Drive / Atlassian / HubSpot / 等)。用戶經 Claude Desktop Settings → Extensions → Browse 一鍵安裝,credential 由 AI tool secure storage / OS credential store / connector storage 管理。
|
|
42
57
|
|
|
43
58
|
紀律:
|
|
44
|
-
- AI 可使用
|
|
59
|
+
- AI 可使用 active runtime 已暴露、且已讀取 tool description / input schema 嘅 Connector tool 直接 read / write
|
|
45
60
|
- Write operations 必 read-back verify 後才聲稱成功(沿用 `packs/knowledge.md` Rule 6 紀律)
|
|
46
61
|
- Auth 失敗(token expired / revoked)即 surface「請開 Claude Desktop Settings → Extensions → 重新 authenticate」+ 唔嘗試自動 fix
|
|
47
62
|
|
|
48
|
-
####
|
|
63
|
+
#### 3.2 MCPs(community / custom)
|
|
49
64
|
|
|
50
65
|
非 Anthropic 官方 vetted 嘅 MCP server,譬如 community 開發、用戶自建。需要 manual config(譬如 `~/.config/claude-code/mcp.json`)。
|
|
51
66
|
|
|
52
67
|
紀律:
|
|
53
|
-
- 用
|
|
68
|
+
- 用 active runtime 已暴露、且已讀取 tool description / input schema 嘅 MCP tool(同 Connectors 一樣遵守 schema-first)
|
|
54
69
|
- 因為非官方 vetted,AI 對 write operation 加倍小心:destructive writes 必先 dry-run + 用戶 confirm(沿用 `packs/safety.md` Rule 1)
|
|
55
70
|
- Server 失靈(process crash / config error)即 surface「請檢查 MCP config + 重啟 AI tool」+ 唔嘗試自動 fix
|
|
56
71
|
|
|
57
|
-
####
|
|
72
|
+
#### 3.3 Plugins(Claude Code plugin bundle)
|
|
58
73
|
|
|
59
74
|
distribution format,bundle = Skills + MCP server config + hooks。用戶經 `/plugin` command 安裝。
|
|
60
75
|
|
|
@@ -63,7 +78,7 @@ distribution format,bundle = Skills + MCP server config + hooks。用戶經 `/
|
|
|
63
78
|
- 若 plugin 提供 skill,AI 按 skill 觸發條件自動 invoke(同 system skill 紀律一致)
|
|
64
79
|
- 若 plugin 提供 MCP server,當 Connector / MCP 處理(見 2.1 / 2.2)
|
|
65
80
|
|
|
66
|
-
####
|
|
81
|
+
#### 3.4 Skills(SKILL.md instruction set)
|
|
67
82
|
|
|
68
83
|
content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
69
84
|
|
|
@@ -72,7 +87,7 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
72
87
|
- Skill 內容屬 instruction overlay,與 rule pack 紀律 layer 共存
|
|
73
88
|
- 若 skill 與 rule pack 紀律有 conflict,rule pack(safety / governance 等)優先
|
|
74
89
|
|
|
75
|
-
###
|
|
90
|
+
### 4. Source-of-truth Architecture(多層持久化組合)
|
|
76
91
|
|
|
77
92
|
當項目用多個整合構成 source-of-truth 架構(譬如 Notion DB Index + 本機真源 + Google Drive 參考檔),AI 必先讀 `dev/PROJECT_INDEX.md` `## Installed Integrations` `### Source-of-truth Architecture` sub-table,識別每層分工:
|
|
78
93
|
|
|
@@ -85,7 +100,7 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
85
100
|
|
|
86
101
|
每個 Layer 由邊個 Integration 承擔由 PROJECT_INDEX schema 明示。AI 唔可越層(譬如將 Index 當真源、將 Working draft 直接 push 上 mirror)。
|
|
87
102
|
|
|
88
|
-
###
|
|
103
|
+
### 5. Cross-session Lifecycle(6 階段)
|
|
89
104
|
|
|
90
105
|
#### 階段 0 — First-contact declaration(onboarding 階段)
|
|
91
106
|
|
|
@@ -101,10 +116,10 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
101
116
|
|
|
102
117
|
#### 階段 3 — Startup availability probe
|
|
103
118
|
|
|
104
|
-
新 AI session 開工讀 PROJECT_INDEX 後,對每個 declared Integration 跑 minimal capability probe
|
|
119
|
+
新 AI session 開工讀 PROJECT_INDEX 後,對每個 declared Integration 跑 minimal capability probe。Probe 必須使用 active runtime 目前暴露、且已讀取 description / input schema 嘅 tool;不可照抄舊例子或憑記憶猜 tool name / arguments。
|
|
105
120
|
|
|
106
121
|
- Probe success → update `Last Verified` cell + 進入正常 task loop
|
|
107
|
-
- Probe fail(current AI tool 冇裝 / auth expired / network 問題)→ startup card warn 一句「⚠️ Boundary:
|
|
122
|
+
- Probe fail(current AI tool 冇裝 / auth expired / network 問題)→ startup card warn 一句「⚠️ Boundary: <tool> declared but unavailable in this runtime; will fallback to paste flow when that surface is touched」;用戶決定點處理
|
|
108
123
|
|
|
109
124
|
#### 階段 4 — Task execution(knowledge pack Rule 5 配合)
|
|
110
125
|
|
|
@@ -130,19 +145,21 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
130
145
|
## Rules
|
|
131
146
|
|
|
132
147
|
1. **Credential 機密分離**:AI 不要求用戶喺對話貼 credential;識別 credential prefix 即 redact + warn rotate;寫 PROJECT_INDEX 前 self-check 無 credential leak。
|
|
133
|
-
2. **
|
|
134
|
-
3. **
|
|
135
|
-
4. **
|
|
136
|
-
5. **
|
|
137
|
-
6. **
|
|
138
|
-
7. **
|
|
139
|
-
8. **
|
|
140
|
-
9. **
|
|
148
|
+
2. **External Tool Usage Verification Gate**:任務涉及外部工具前,先分類工具層並核對 current runtime schema、官方文件、官方型別 / sample、或有版本日期嘅本地 runbook;不能核實即 blocked / unverified,唔用模型記憶試錯。
|
|
149
|
+
3. **Declaration before use**:任務涉及外部工具前,先讀 `dev/PROJECT_INDEX.md` `## Installed Integrations`;無 declaration 即 ask user about Integration status,唔自己假設未裝。
|
|
150
|
+
4. **Connector-first default**:當 declared Integration functional,優先使用 active runtime 已暴露且已讀 schema 嘅 direct tool call;paste fallback 只當 Integration unavailable 時。
|
|
151
|
+
5. **Write operations read-back verify**:所有外部 write(Notion create-page / Drive upload / Slack post 等)必 read-back 對齊後才聲稱 success。
|
|
152
|
+
6. **No auto-fix credential / auth issues**:Auth 失靈即 surface 俾用戶處理(指向 AI 工具設定界面),AI 唔嘗試自動 fix。
|
|
153
|
+
7. **Cross-tool capability awareness**:新 session 開工 verify availability;若 current AI tool 冇相應整合,startup card warn + fallback。
|
|
154
|
+
8. **Source-of-truth layer 唔越界**:真源層 AI 不直接寫;Index 層 AI 經 Connector 讀寫;Mirror 層用戶手動同步;Working draft 層 AI 直接 read/write 本機。
|
|
155
|
+
9. **Drift event mandatory recording**:任何整合失靈 / unavailable 即更新 PROJECT_INDEX `Last Verified` cell + SESSION_LOG drift narrative + handoff next-session prompt 提示。
|
|
156
|
+
10. **Plugin / Skill 紀律 subordinate**:若 Plugin 攜帶 Skill 觸發,與 rule pack 紀律 layer 共存;conflict 時 rule pack(safety / governance / closeout)優先。
|
|
141
157
|
|
|
142
158
|
## Checks
|
|
143
159
|
|
|
144
160
|
- 開工 verify `dev/PROJECT_INDEX.md` `## Installed Integrations` section 存在 + 4 subsection schema 完整
|
|
145
|
-
- 開工對每 declared Integration 跑 capability probe,update `Last Verified` cell
|
|
161
|
+
- 開工對每 declared Integration 跑 capability probe,probe 前先讀 current runtime tool description / input schema,update `Last Verified` cell
|
|
162
|
+
- 外部工具首次調用、寫入、不可逆操作、API / SDK / CLI / URI / plugin API 使用、或工具錯誤後重試前,確認已核對 current runtime schema / 官方文件 / 官方型別 / 官方 sample / 有版本日期嘅 runbook
|
|
146
163
|
- 任何 mid-session Integration drift 即 surface + 紀錄
|
|
147
164
|
- Closeout 前確認 `Last Verified` cell 已 update 為今次 session 結果
|
|
148
165
|
- Credential leak self-check 對 PROJECT_INDEX + SESSION_HANDOFF + SESSION_LOG 任何 write
|
|
@@ -163,7 +180,10 @@ content format,由 Plugin 攜帶或 user-level / project-level 直接安裝。
|
|
|
163
180
|
| Anti-pattern | 點解唔做 | 正確做法 |
|
|
164
181
|
|---|---|---|
|
|
165
182
|
| 用戶提到 Notion / Google Drive 即假設冇 Connector,直接列 paste packet | 違反 2026-05 reality:Connector ecosystem 已成熟,paste-only fallback 不應係 default | 先 read PROJECT_INDEX Installed Integrations;無 declaration 即 ask user about Integration status |
|
|
166
|
-
|
|
|
183
|
+
| 憑模型記憶猜 Notion / Google Drive / Obsidian / GitHub tool name、endpoint、CLI flag、URI param、plugin API | 會把過時訓練資料當現行指令,造成 unknown tool / invalid args / 400 / 404 / permission error 循環 | 先核對 active runtime tool schema、官方文件、官方型別 / sample、或有版本日期嘅本地 runbook;不能核實即 blocked / unverified |
|
|
184
|
+
| Connector 介紹頁或舊例子當成可執行 schema | 介紹頁通常唔等於 current runtime 實際暴露 tool name / input schema | 以 active runtime tool list / schema 為準;官方文件只作 raw API / SDK / CLI / URI 或故障排查真源 |
|
|
185
|
+
| unknown tool / invalid args 後連續改名或改參數試錯 | 同類盲試會製造新錯誤,掩蓋真正 schema / docs 缺口 | 停止同類重試,回到 External Tool Usage Verification Gate |
|
|
186
|
+
| 將 credential value 寫入 PROJECT_INDEX / SESSION_HANDOFF / SESSION_LOG | 違反機密分離原則 + git history 永久保留泄露 | Credential reference 只記指向(譬如「AI tool secure storage」/「env var name only」),永不記 value |
|
|
167
187
|
| 用戶喺對話貼 credential value,AI 直接 用 / 紀錄 | 違反 enforcement Rule 1 + 用戶可能誤泄露 | 即時 redact + warn 用戶 rotate token + 解釋機密分離原則 |
|
|
168
188
|
| Auth 失靈即嘗試自動 fix / re-auth flow | 越界(屬 AI tool + 用戶範圍)+ 可能引入 credential exposure | Surface 失敗 + 指向 AI 工具設定界面 + 唔自動 fix |
|
|
169
189
|
| Connector 寫入後唔 read-back verify | Write 可能 silently fail(rate limit / partial write)—— 用戶以為 success | 必 read-back verify 後才聲稱 success(沿用 knowledge Rule 6) |
|
package/packs/knowledge.md
CHANGED
|
@@ -15,11 +15,11 @@ Use for external notes, knowledge bases, Notion, Obsidian, Drive, docs repositor
|
|
|
15
15
|
2. Record access mode and sync expectation before relying on external content.
|
|
16
16
|
3. Prefer local durable files for installable runtime text unless the project declares otherwise.
|
|
17
17
|
4. Do not perform destructive external writes without explicit confirmation.
|
|
18
|
-
5. Connector-first default for external read/write (R-030 Integration governance discipline; works together with `dev/rules/integrations.md`):
|
|
19
|
-
(a) Before reading or writing external knowledge, check `dev/PROJECT_INDEX.md` `## Installed Integrations` for declared tool availability.
|
|
20
|
-
(b) If a declared Integration is functional in the current session (verified during startup probe per `runtime-core/AGENTS.core.md` Section 1): use the
|
|
21
|
-
(c) If a declared Integration is unavailable in the current session (different AI tool / Connector not configured / auth expired): degrade to manual paste packet workflow + flag drift in the mid-task summary + update `Last Verified` cell at closeout.
|
|
22
|
-
(d) If no declaration exists in `## Installed Integrations` but the task references an external tool: ask the user about Integration status before proceeding (do not silently assume paste fallback). Backward-compat: existing v0.2.x projects with no Installed Integrations section follow path (d) — the section template auto-appends on upgrade but content stays empty until user declares; AI behavior degrades gracefully to ask-user fallback.
|
|
18
|
+
5. Connector-first default for external read/write (R-030 Integration governance discipline; works together with `dev/rules/integrations.md`):
|
|
19
|
+
(a) Before reading or writing external knowledge, check `dev/PROJECT_INDEX.md` `## Installed Integrations` for declared tool availability.
|
|
20
|
+
(b) If a declared Integration is functional in the current session (verified during startup probe per `runtime-core/AGENTS.core.md` Section 1): use only the active runtime tool calls whose current name, description, and input schema have been inspected under the External Tool Usage Verification Gate. Do not invent `mcp__*` names or arguments from examples or memory.
|
|
21
|
+
(c) If a declared Integration is unavailable in the current session (different AI tool / Connector not configured / auth expired): degrade to manual paste packet workflow + flag drift in the mid-task summary + update `Last Verified` cell at closeout.
|
|
22
|
+
(d) If no declaration exists in `## Installed Integrations` but the task references an external tool: ask the user about Integration status before proceeding (do not silently assume paste fallback). Backward-compat: existing v0.2.x projects with no Installed Integrations section follow path (d) — the section template auto-appends on upgrade but content stays empty until user declares; AI behavior degrades gracefully to ask-user fallback.
|
|
23
23
|
6. When writing to an external mirror or index, read back the written record before claiming sync success.
|
|
24
24
|
7. Preserve local file paths as plain text, code, or structured rich text fields when the external tool parses Markdown links or escape characters.
|
|
25
25
|
|
package/packs/onboarding.md
CHANGED
|
@@ -291,7 +291,7 @@ Onboarding 第一個可見回覆只能有一張完整啟動卡,然後直接接
|
|
|
291
291
|
- AI sample wording:
|
|
292
292
|
> 「我會將你已聲明的工具寫入項目登記表:
|
|
293
293
|
>
|
|
294
|
-
> - `## Installed Integrations` `### Connectors` 表填 Notion / Google Drive 等 entries(每個含 Project Usage / Access Scope / Specific Instance / Credential
|
|
294
|
+
> - `## Installed Integrations` `### Connectors` 表填 Notion / Google Drive 等 entries(每個含 Project Usage / Access Scope / Specific Instance / Credential Reference(no value)/ Declared / Last Verified)
|
|
295
295
|
> - `## Installed Integrations` `### Source-of-truth Architecture` sub-table 填多層分工
|
|
296
296
|
> - 既有 `## External Sources` 表的 `via` column 引用對應 Connector entry
|
|
297
297
|
>
|
|
@@ -303,9 +303,9 @@ Onboarding 第一個可見回覆只能有一張完整啟動卡,然後直接接
|
|
|
303
303
|
- AI sample wording:
|
|
304
304
|
> 「聲明已寫好。我會檢查每個外部工具在本次對話是否可用:
|
|
305
305
|
>
|
|
306
|
-
> -
|
|
307
|
-
> -
|
|
308
|
-
> -
|
|
306
|
+
> - Connector / MCP:先讀本次 runtime 暴露的工具名稱、描述與輸入 schema,再做最小 probe
|
|
307
|
+
> - API / SDK / CLI / URI / plugin API:先查官方文件、官方型別 / sample,或有版本日期的本地 runbook
|
|
308
|
+
> - 不能核實的工具:標記 blocked / unverified,不憑記憶試錯
|
|
309
309
|
>
|
|
310
310
|
> 檢查結果會寫入每行 `Last Verified` 欄位。如果任何外部工具不可用(例如目前 AI 工具未配對應 MCP),我會直接說明,讓你決定如何處理。
|
|
311
311
|
>
|
package/packs/safety.md
CHANGED
|
@@ -21,13 +21,13 @@ Use for file operations, shell commands, Git changes, package managers, installe
|
|
|
21
21
|
7. On macOS / Linux, do not run `rm -rf`, `sudo rm`, recursive `chmod`, recursive `chown`, or destructive wildcard operations unless the user explicitly requested the operation and target paths are listed and verified.
|
|
22
22
|
8. Do not run `git reset --hard`, branch deletion, tag deletion, force push, or history rewrite unless the user explicitly requested it and affected refs/files are listed.
|
|
23
23
|
9. Before staging or committing, inspect current status and avoid staging unrelated parent-repo, sibling-directory, generated, credential, or user-owned changes.
|
|
24
|
-
10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, or release tools, verify current official documentation or project-local runbooks.
|
|
25
|
-
(a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server
|
|
26
|
-
(b) Community / custom MCP servers (user-installed via manual config): treat with extra caution — destructive writes require dry-run + user confirmation; verify server behavior against project-local runbook if available.
|
|
27
|
-
(c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
|
|
24
|
+
10. Before using external APIs, SDKs, CLIs, package managers, deploy tools, cloud tools, or release tools, verify current official documentation or project-local runbooks. For external tools, first apply the External Tool Usage Verification Gate in `dev/rules/integrations.md`: inspect current runtime tool schema for Connector / MCP calls, and use current official docs, official type definitions, official samples, or versioned local runbooks for raw API / SDK / CLI / URI / plugin API work. Differentiate three layers of external access:
|
|
25
|
+
(a) Anthropic-vetted Connectors (e.g. Notion / Google Drive / Slack via Claude Desktop Extensions): trust the vetted MCP server boundary only after inspecting the active runtime tool name, description, and input schema; still verify destructive write parameters before invocation.
|
|
26
|
+
(b) Community / custom MCP servers (user-installed via manual config): treat with extra caution — destructive writes require dry-run + user confirmation; verify server behavior against current tool schema and project-local runbook if available.
|
|
27
|
+
(c) Raw external APIs / SDKs / CLIs (no MCP layer): full Rule 10 verification of official docs required; mark unverified if blocked.
|
|
28
28
|
11. Do not print, copy, log, commit, upload, or generate files containing secret values. Use redacted placeholders or line references.
|
|
29
29
|
12. Credential leak prevention (R-030 Integration governance):
|
|
30
|
-
(a) Never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens) in any project file. Credentials live exclusively in AI tool secure storage
|
|
30
|
+
(a) Never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens) in any project file. Credentials live exclusively in AI tool secure storage, OS credential stores, AI tool config, user-managed secret stores, or env indirection; if env is used, project files may record only the env var name, never the value.
|
|
31
31
|
(b) Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) — if a value matching any prefix appears in conversation, redact immediately and warn the user to rotate the token.
|
|
32
32
|
(c) Before writing to `dev/PROJECT_INDEX.md` `## Installed Integrations`, `dev/SESSION_HANDOFF.md`, or `dev/SESSION_LOG.md`, self-check that no credential value is present; doctor `checkInstalledIntegrationsCredentialLeak()` enforces this at QC.
|
|
33
33
|
(d) Auth failure (token expired / revoked / rate-limit) surfaces to the user with a pointer to the AI tool's own settings interface; do not attempt to auto-fix auth or re-auth flow (out of scope for Kit governance).
|
|
@@ -29,7 +29,7 @@ When creating or materially changing Markdown files, generated documents, resear
|
|
|
29
29
|
|
|
30
30
|
After reading `dev/PROJECT_INDEX.md`, if `## Installed Integrations` is non-empty, run startup availability probe (R-030 Integration governance discipline; see `dev/rules/integrations.md`):
|
|
31
31
|
|
|
32
|
-
- For each declared Integration under Connectors / MCPs subsection, attempt minimal capability probe
|
|
32
|
+
- For each declared Integration under Connectors / MCPs subsection, attempt a minimal capability probe using the active runtime's currently exposed tool name, description, and input schema. Do not invent `mcp__*` names or arguments from examples or memory.
|
|
33
33
|
- If probe succeeds: update the corresponding `Last Verified` cell to today's date; proceed normally.
|
|
34
34
|
- If probe fails (current AI tool lacks the Connector / auth expired / network issue): print warning in the startup card (`⚠️ Boundary` line) noting which Integration is declared-but-unavailable + that this session will fallback to paste flow when that external surface is touched. Do not attempt to auto-fix auth or credential issues; surface to the user to handle via the AI tool's own settings interface.
|
|
35
35
|
- Credential separation: AI must never request, log, or persist credential values (API keys / OAuth tokens / app secrets / refresh tokens). Credentials live in OS-level secure storage or AI-tool-specific config, never in `dev/*` files. Recognize common credential prefixes (`sk-`, `sk-ant-`, `ntn_`, `secret_`, `ya29.`, `1//`, `xoxp-`, `xoxb-`, `ghp_`, `gho_`, `ghs_`, `github_pat_`, `sl.`, `AKIA`, `AIza`) and redact + warn the user to rotate the token if accidentally pasted.
|
|
@@ -58,21 +58,21 @@ Reachable means the source can be found. It does not mean the source has been re
|
|
|
58
58
|
|
|
59
59
|
## Installed Integrations
|
|
60
60
|
|
|
61
|
-
> ⚠️ **機密分離原則**:本 section 只記錄 **項目使用紀錄** + **公開參考座標**(Notion DB 名 / URL / folder path 等),**絕對不記錄 API key / OAuth token / 任何 credential value**。Credential 應由 AI 工具自身 secure storage
|
|
61
|
+
> ⚠️ **機密分離原則**:本 section 只記錄 **項目使用紀錄** + **公開參考座標**(Notion DB 名 / URL / folder path 等),**絕對不記錄 API key / OAuth token / 任何 credential value**。Credential 應由 AI 工具自身 secure storage / OS credential store / tool config / user-managed secret store 管理;若使用 env,只可記錄 env var name,不可讀取、貼出或保存 value。AI 寫入本 section 前必 self-check 確認無 credential leak;doctor 對本 section + SESSION_HANDOFF + SESSION_LOG 強制 grep credential prefix patterns(`sk-` / `ntn_` / `ya29.` / `xoxp-` / `ghp_` / `sl.` / `AKIA` / `AIza` 等)。
|
|
62
62
|
|
|
63
63
|
> 用途:新 AI session 開工讀本 section 知道項目可用嘅外部工具能力 + 各自分工。Declare 一次後跨 session AI 都會 leverage;每個 entry 必含 `Declared` + `Last Verified` 防漂移。
|
|
64
64
|
|
|
65
65
|
### Connectors(Anthropic 官方 vetted)
|
|
66
66
|
|
|
67
|
-
| Tool | Project Usage | Access Scope | Specific Instance | Credential
|
|
67
|
+
| Tool | Project Usage | Access Scope | Specific Instance | Credential Reference(no value) | Declared | Last Verified |
|
|
68
68
|
|------|---------------|--------------|-------------------|---------------------|----------|---------------|
|
|
69
|
-
| TBD | TBD(譬如 DB Index 記真源 path / 持久化參考檔儲存) | read / read+write | TBD(譬如 DB 名 + URL / folder path) | TBD(譬如 `
|
|
69
|
+
| TBD | TBD(譬如 DB Index 記真源 path / 持久化參考檔儲存) | read / read+write | TBD(譬如 DB 名 + URL / folder path) | TBD(譬如 `AI tool secure storage` / `OS credential store`) | TBD | TBD |
|
|
70
70
|
|
|
71
71
|
### MCPs(community / custom)
|
|
72
72
|
|
|
73
|
-
| Server | Source | Project Usage | Credential
|
|
73
|
+
| Server | Source | Project Usage | Credential Reference(no value) | Declared | Last Verified |
|
|
74
74
|
|--------|--------|---------------|---------------------|----------|---------------|
|
|
75
|
-
| TBD | TBD(譬如 GitHub repo URL) | TBD | TBD(譬如 `
|
|
75
|
+
| TBD | TBD(譬如 GitHub repo URL) | TBD | TBD(譬如 `tool config + env var name only` / `user-managed secret store`) | TBD | TBD |
|
|
76
76
|
|
|
77
77
|
### Plugins(Claude Code plugin bundle)
|
|
78
78
|
|
|
@@ -12,7 +12,7 @@ Stable facts that should survive across sessions. Update only when they change,
|
|
|
12
12
|
3. Governance model: TBD
|
|
13
13
|
4. Source-of-truth ownership: TBD
|
|
14
14
|
5. Release / publish boundary: TBD
|
|
15
|
-
6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` section is the project's authoritative declaration of installed Connectors / MCPs / Plugins / Skills + Source-of-truth Architecture sub-table. New AI session must read it after governance reads and run availability probe per `runtime-core/AGENTS.core.md` Section 1. Credential values never appear here or in any `dev/*` file —
|
|
15
|
+
6. Installed Integrations registry: `dev/PROJECT_INDEX.md` `## Installed Integrations` section is the project's authoritative declaration of installed Connectors / MCPs / Plugins / Skills + Source-of-truth Architecture sub-table. New AI session must read it after governance reads and run availability probe per `runtime-core/AGENTS.core.md` Section 1. Credential values never appear here or in any `dev/*` file — only credential references such as AI tool secure storage, OS credential store, tool config, user-managed secret store, or env var name may be recorded.
|
|
16
16
|
|
|
17
17
|
<!-- ack:section:closeout-reconciled-state -->
|
|
18
18
|
## Closeout-Reconciled State
|