@akagilnc/pi-workflow-roles 0.1.3771 → 0.1.3789

package/src/collector-handbook.ts

@@ -0,0 +1,194 @@
+/**
+ * Collector bot handbook — opaque working memory under the book topology.
+ * Runtime stores and delivers UTF-8 text only; never parses free text into
+ * code state rules (parent #673 D3 / #677).
+ *
+ * Placement reuses the machine ledger home (ADR 0048) when the admitted
+ * session already sits under books/<bookKey>/ — no parallel persistence frame.
+ */
+import { readFile } from "node:fs/promises";
+import { join, sep } from "node:path";
+
+import { writeFileAtomically } from "./atomic-write.ts";
+import {
+  activationBookDirectory,
+  assertLedgerFileInsideHome,
+  ensureRealDirectoryTree,
+  resolveActivationLedgerHomeForPath,
+} from "./activation-ledger-topology.ts";
+import { COLLECTOR_HANDBOOK_MAX_BYTES } from "./collector-tool-schemas.ts";
+
+export type CollectorHandbookScope = "general" | "repo";
+
+export type CollectorHandbookRead = {
+  readonly general: string;
+  readonly repo: string;
+  readonly generalSource: "book" | "seed" | "empty";
+  readonly repoSource: "book" | "empty";
+  readonly generalPath: string;
+  readonly repoPath: string;
+};
+
+export type CollectorHandbookWriteResult = {
+  readonly scope: CollectorHandbookScope;
+  readonly path: string;
+  readonly byteLength: number;
+};
+
+export type CollectorHandbookStore = {
+  readonly root: string;
+  readonly repositoryCanonical: string;
+  read(): Promise<CollectorHandbookRead>;
+  write(scope: CollectorHandbookScope, body: string): Promise<CollectorHandbookWriteResult>;
+};
+
+export type CollectorHandbookPlacement = {
+  readonly ledgerHome: string;
+  readonly bookKey: string;
+  readonly root: string;
+};
+
+/**
+ * Derive handbook root from an admitted session/run path under
+ * `.ak-roles/books/<bookKey>/...`. Fails closed when topology is absent.
+ */
+export function resolveCollectorHandbookRoot(sessionPath: string): CollectorHandbookPlacement {
+  if (typeof sessionPath !== "string" || sessionPath.trim().length === 0) {
+    throw new Error("通进司手册要求非空 session 路径，且位于 books/<bookKey>/");
+  }
+  // Platform path segments only — never rewrite non-separator characters (POSIX `\\` is literal).
+  const segments = sessionPath.split(sep);
+  let bookKey: string | undefined;
+  for (let i = 0; i + 3 < segments.length; i += 1) {
+    if (segments[i] === ".ak-roles" && segments[i + 1] === "books") {
+      const candidate = segments[i + 2]!;
+      // Require a following segment so bookKey is a true path component under books/.
+      if (candidate.length > 0) {
+        bookKey = candidate;
+        break;
+      }
+    }
+  }
+  if (bookKey === undefined) {
+    throw new Error(
+      `通进司手册要求 session 位于 books/<bookKey>/；收到 ${sessionPath}`,
+    );
+  }
+  if (bookKey === "." || bookKey === "..") {
+    throw new Error(`通进司手册拒绝不安全 bookKey ${JSON.stringify(bookKey)}`);
+  }
+  const ledgerHome = resolveActivationLedgerHomeForPath(sessionPath);
+  const root = join(activationBookDirectory(ledgerHome, bookKey), "collector-handbook");
+  return { ledgerHome, bookKey, root };
+}
+
+/** Flat repo file name under handbook/repos/ — avoids nested owner/repo dirs. */
+function collectorHandbookRepoFileName(repositoryCanonical: string): string {
+  if (!/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(repositoryCanonical)) {
+    throw new Error(
+      `通进司手册仓库文件要求规范 owner/repo，收到 ${JSON.stringify(repositoryCanonical)}`,
+    );
+  }
+  return `${repositoryCanonical.replaceAll("/", "__")}.md`;
+}
+
+export function createCollectorHandbookStore(input: {
+  readonly ledgerHome: string;
+  readonly handbookRoot: string;
+  readonly repositoryCanonical: string;
+  readonly seedGeneral?: string;
+}): CollectorHandbookStore {
+  const generalPath = join(input.handbookRoot, "general.md");
+  const repoDir = join(input.handbookRoot, "repos");
+  const repoPath = join(repoDir, collectorHandbookRepoFileName(input.repositoryCanonical));
+
+  /**
+   * ADR 0038: confine at the real read seam. Parent dirs must be physical under
+   * ledger home; the leaf must not be a pre-existing symlink (even in-home).
+   */
+  /** Sole UTF-8 budget seam — write and read share COLLECTOR_HANDBOOK_MAX_BYTES. */
+  const assertHandbookBudget = (body: string, label: string): number => {
+    const byteLength = Buffer.byteLength(body, "utf8");
+    if (byteLength > COLLECTOR_HANDBOOK_MAX_BYTES) {
+      throw new Error(
+        `通进司手册${label} UTF-8 至多 ${COLLECTOR_HANDBOOK_MAX_BYTES} 字节，收到 ${byteLength}`,
+      );
+    }
+    return byteLength;
+  };
+
+  const readOptional = async (path: string, parentDir: string): Promise<string | undefined> => {
+    ensureRealDirectoryTree(input.ledgerHome, parentDir);
+    assertLedgerFileInsideHome(path, input.ledgerHome);
+    try {
+      const body = await readFile(path, "utf8");
+      assertHandbookBudget(body, "正文");
+      return body;
+    } catch (error) {
+      if (isNotFound(error)) return undefined;
+      throw error;
+    }
+  };
+
+  return {
+    root: input.handbookRoot,
+    repositoryCanonical: input.repositoryCanonical,
+    async read() {
+      const bookGeneral = await readOptional(generalPath, input.handbookRoot);
+      const bookRepo = await readOptional(repoPath, repoDir);
+      if (bookGeneral !== undefined) {
+        return {
+          general: bookGeneral,
+          repo: bookRepo ?? "",
+          generalSource: "book",
+          repoSource: bookRepo === undefined ? "empty" : "book",
+          generalPath,
+          repoPath,
+        };
+      }
+      const seed = input.seedGeneral;
+      if (typeof seed === "string" && seed.length > 0) {
+        assertHandbookBudget(seed, "正文");
+        return {
+          general: seed,
+          repo: bookRepo ?? "",
+          generalSource: "seed",
+          repoSource: bookRepo === undefined ? "empty" : "book",
+          generalPath,
+          repoPath,
+        };
+      }
+      return {
+        general: "",
+        repo: bookRepo ?? "",
+        generalSource: "empty",
+        repoSource: bookRepo === undefined ? "empty" : "book",
+        generalPath,
+        repoPath,
+      };
+    },
+    async write(scope, body) {
+      // body string shape = collectorHandbookWriteArgsSchema; byte budget is business (UTF-8).
+      const byteLength = assertHandbookBudget(body, "正文");
+      ensureRealDirectoryTree(input.ledgerHome, input.handbookRoot);
+      const path = scope === "general" ? generalPath : repoPath;
+      if (scope === "repo") {
+        ensureRealDirectoryTree(input.ledgerHome, repoDir);
+      }
+      assertLedgerFileInsideHome(path, input.ledgerHome);
+      await writeFileAtomically(path, body);
+      return {
+        scope,
+        path,
+        byteLength,
+      };
+    },
+  };
+}
+
+function isNotFound(error: unknown): boolean {
+  return typeof error === "object"
+    && error !== null
+    && "code" in error
+    && (error as { code?: unknown }).code === "ENOENT";
+}

package/src/collector-ledger.ts

@@ -1,5 +1,3 @@
-import Value from "typebox/value";
-
 import type { CollectorManifest, CollectorRepository } from "./collector-config.ts";
 import {
   applyEvidenceVersionHistory,
@@ -26,13 +24,6 @@ import {
   type GitHubPullRequest,
 } from "./collector-github.ts";
 import { CollectorNonOpenRequestError } from "./collector-identity.ts";
-import {
-  collectorObserveArgsSchema,
-  collectorOutputArgsSchema,
-  collectorReadArgsSchema,
-  collectorRequestArgsSchema,
-  collectorWaitArgsSchema,
-} from "./collector-tool-schemas.ts";
 import { COLLECTOR_OUTPUT_TOOL } from "./package-contracts/collector-output.ts";
 
 export const COLLECTOR_OBSERVE_TOOL = "ak_collector_observe";
@@ -41,6 +32,8 @@ export const COLLECTOR_REQUEST_TOOL = "ak_collector_request";
 export const COLLECTOR_WAIT_TOOL = "ak_collector_wait";
 /** #676 A: role-decided target bind — business tool, ledger-booked. */
 export const COLLECTOR_BIND_TARGET_TOOL = "ak_collector_bind_target";
+/** #677: opaque handbook write — business tool, ledger-booked. */
+export const COLLECTOR_HANDBOOK_WRITE_TOOL = "ak_collector_handbook_write";
 export { COLLECTOR_OUTPUT_TOOL };
 
 export const COLLECTOR_OPERATIONAL_TOOLS = [
@@ -49,6 +42,7 @@ export const COLLECTOR_OPERATIONAL_TOOLS = [
   COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
+  COLLECTOR_HANDBOOK_WRITE_TOOL,
 ] as const;
 
 /**
@@ -57,7 +51,7 @@ export const COLLECTOR_OPERATIONAL_TOOLS = [
  * (evidenceId + htmlUrl) and is preserved in the volume, never unconditionally
  * transcribed into model context or receipt.
  */
-export const COLLECTOR_OBSERVE_BODY_HEAD_BYTES = 512;
+const COLLECTOR_OBSERVE_BODY_HEAD_BYTES = 512;
 
 function utf8SafePrefix(text: string, maxBytes: number): string {
   if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
@@ -108,7 +102,7 @@ export type ObserveModelView = {
  * (collector-side; provider-visible observe details carry only this bounded
  * projection), never unconditionally transcribed into model context.
  */
-export function projectObserveContextView(modelView: ObserveModelView): ObserveModelView {
+function projectObserveContextView(modelView: ObserveModelView): ObserveModelView {
   return {
     ...modelView,
     evidence: modelView.evidence.map((entry) =>
@@ -121,9 +115,9 @@ export function projectObserveContextView(modelView: ObserveModelView): ObserveM
 export type CollectorOperationalTool = (typeof COLLECTOR_OPERATIONAL_TOOLS)[number];
 
 export const COLLECTOR_ACTIVATION_ENTRY_TYPE = "ak-collector-activation" as const;
-export const COLLECTOR_SNAPSHOT_ENTRY_TYPE = "ak-collector-snapshot" as const;
-export const COLLECTOR_REQUEST_ENTRY_TYPE = "ak-collector-request" as const;
-export const COLLECTOR_WAIT_ENTRY_TYPE = "ak-collector-wait" as const;
+const COLLECTOR_SNAPSHOT_ENTRY_TYPE = "ak-collector-snapshot" as const;
+const COLLECTOR_REQUEST_ENTRY_TYPE = "ak-collector-request" as const;
+const COLLECTOR_WAIT_ENTRY_TYPE = "ak-collector-wait" as const;
 
 export type CollectorRequestAttempt = {
   attemptId: string;
@@ -217,7 +211,7 @@ export type CollectorLedger = {
   }>;
 
   request(
-    input: { requestId: string; snapshotId: string },
+    input: { requestId: string; snapshotId: string; body?: string },
     transport: CollectorGitHubTransport,
     clock: CollectorClock,
     signal?: AbortSignal,
@@ -243,29 +237,6 @@ function isOperationalTool(name: string): name is CollectorOperationalTool {
   return (COLLECTOR_OPERATIONAL_TOOLS as readonly string[]).includes(name);
 }
 
-/** Shared Check owner for Collector tool argument shapes (schema seam, not batch law). */
-export function collectorToolArgumentsValid(
-  name: string,
-  args: unknown,
-): boolean {
-  // Residual envelope: reject missing/null args before schema check.
-  if (args === undefined || args === null) return false;
-  switch (name) {
-    case COLLECTOR_OBSERVE_TOOL:
-      return Value.Check(collectorObserveArgsSchema, args);
-    case COLLECTOR_READ_TOOL:
-      return Value.Check(collectorReadArgsSchema, args);
-    case COLLECTOR_REQUEST_TOOL:
-      return Value.Check(collectorRequestArgsSchema, args);
-    case COLLECTOR_WAIT_TOOL:
-      return Value.Check(collectorWaitArgsSchema, args);
-    case COLLECTOR_OUTPUT_TOOL:
-      return Value.Check(collectorOutputArgsSchema, args);
-    default:
-      return false;
-  }
-}
-
 export function createCollectorLedger(
   config: CollectorConfigState,
   options?: CollectorLedgerOptions,
@@ -335,9 +306,7 @@ export function createCollectorLedger(
 
   const requireBoundPr = (): number => {
     if (config.prNumber === undefined) {
-      throw new Error(
-        "Collector PR target is unbound; call ak_collector_bind_target with the role-decided issue/PR or pass --pr",
-      );
+      throw new Error("通进司 PR 目标未绑定");
     }
     return config.prNumber;
   };
@@ -675,11 +644,11 @@ export function createCollectorLedger(
         throw new Error("通进司已产出输出候选，本局不再受理目标绑定");
       }
       if (!Number.isSafeInteger(prNumber) || prNumber < 1) {
-        throw new Error("Collector bind target requires a positive safe-integer PR number");
+        throw new Error("通进司绑定目标要求正安全整数 PR 号");
       }
       if (config.prNumber !== undefined && config.prNumber !== prNumber) {
         throw new Error(
-          `Collector target already bound to PR ${config.prNumber}; cannot rebind to ${prNumber}`,
+          `通进司目标已绑定 PR ${config.prNumber}，不可改绑为 ${prNumber}`,
         );
       }
       config.prNumber = prNumber;
@@ -915,9 +884,25 @@ export function createCollectorLedger(
         throw latchFatal("通进司请求时存在未恢复的传输失败");
       }
 
-      const request = config.manifest.requests.find((item) => item.id === input.requestId);
-      if (request === undefined) {
-        throw new Error(`未知通进司 requestId "${input.requestId}"`);
+      // Sole request identity seam: trim once, then use everywhere (lookup/marker/attemptKey).
+      // Schema pattern rejects leading/trailing whitespace at host; trim still collapses
+      // direct ledger callers and any residual padding into one stable id (#677 D2).
+      if (typeof input.requestId !== "string") {
+        throw new Error("通进司 requestId 须为字符串");
+      }
+      const requestId = input.requestId.trim();
+      if (requestId.length === 0) {
+        throw new Error("通进司 requestId 须为非空（首尾空白不构成身份）");
+      }
+      const configured = config.manifest.requests.find((item) => item.id === requestId);
+      const roleBody = typeof input.body === "string" ? input.body : undefined;
+      if (configured === undefined) {
+        // #677: role-decided trigger from handbook/field activity — body required when not in manifest.
+        if (roleBody === undefined || roleBody.trim().length === 0) {
+          throw new Error(
+            `未知通进司 requestId "${requestId}" 且未提供 body；请提交角色判定的请求正文或使用 request-manifest`,
+          );
+        }
       }
 
       const snapshot = snapshots.find((item) => item.snapshotId === input.snapshotId);
@@ -936,10 +921,12 @@ export function createCollectorLedger(
         throw latchFatal("通进司请求不在资格截止前");
       }
 
+      // Caller manifest body wins when requestId is configured; otherwise role body.
+      const configuredBody = configured?.requestBody ?? roleBody!;
       const { body, marker } = buildCollectorRequestBody({
-        configuredBody: request.requestBody,
+        configuredBody,
         manifestDigest: config.manifest.digest,
-        requestId: request.id,
+        requestId,
         headOid: snapshot.headOid,
       });
       const existingMarker = snapshot.evidenceIds.some((id) => {
@@ -951,7 +938,7 @@ export function createCollectorLedger(
       });
       if (existingMarker) {
         throw new Error(
-          `通进司在此 HEAD 已有同 marker 的已认证请求 "${input.requestId}"`,
+          `通进司在此 HEAD 已有同 marker 的已认证请求 "${requestId}"`,
         );
       }
 
@@ -960,11 +947,11 @@ export function createCollectorLedger(
         config.repository.canonical,
         String(boundPr),
         snapshot.headOid,
-        request.id,
+        requestId,
       ].join("|");
       if (attemptKeys.has(attemptKey)) {
         throw new Error(
-          `通进司进程内请求 "${request.id}" 在 HEAD ${snapshot.headOid} 的 attempt 已用`,
+          `通进司进程内请求 "${requestId}" 在 HEAD ${snapshot.headOid} 的 attempt 已用`,
         );
       }
 
@@ -972,7 +959,7 @@ export function createCollectorLedger(
       const attemptId = sha256Text(`${attemptKey}:${startedAt}`).slice(0, 16);
       const attempt: CollectorRequestAttempt = {
         attemptId,
-        requestId: request.id,
+        requestId,
         observedHead: snapshot.headOid,
         snapshotId: snapshot.snapshotId,
         marker,
@@ -1017,7 +1004,7 @@ export function createCollectorLedger(
         return {
           status: "succeeded",
           attemptId,
-          requestId: request.id,
+          requestId,
           observedHead: snapshot.headOid,
           marker,
           commentEvidenceId: record.evidenceId,
@@ -1032,7 +1019,7 @@ export function createCollectorLedger(
         return {
           status: "ambiguous_loss",
           attemptId,
-          requestId: request.id,
+          requestId,
           observedHead: snapshot.headOid,
           marker,
           diagnostics: result.diagnostics,
@@ -1051,14 +1038,7 @@ export function createCollectorLedger(
       if (activationTime === undefined) {
         throw latchFatal("通进司等待需要激活");
       }
-      if (!Number.isSafeInteger(input.durationMs) || input.durationMs < 1) {
-        throw new Error("通进司等待 durationMs 须为正安全整数");
-      }
-      if (input.durationMs > COLLECTOR_ELIGIBILITY_MS) {
-        throw new Error(
-          `通进司等待 durationMs 至多为 ${COLLECTOR_ELIGIBILITY_MS}`,
-        );
-      }
+      // durationMs shape authority = collectorWaitArgsSchema (host parameters).
       if (pastCutoff(clock)) {
         finalObservationRequired = true;
         throw latchFatal("通进司等待不在资格截止前");

package/src/collector-role.ts

@@ -25,8 +25,14 @@ import {
   listPullRequestNumbersByTicket,
   type CollectorGitHubTransport,
 } from "./collector-github.ts";
+import {
+  createCollectorHandbookStore,
+  resolveCollectorHandbookRoot,
+  type CollectorHandbookStore,
+} from "./collector-handbook.ts";
 import {
   COLLECTOR_BIND_TARGET_TOOL,
+  COLLECTOR_HANDBOOK_WRITE_TOOL,
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_OUTPUT_TOOL,
   COLLECTOR_READ_TOOL,
@@ -42,6 +48,7 @@ import {
 } from "./collector-receipt.ts";
 import {
   collectorBindTargetArgsSchema,
+  collectorHandbookWriteArgsSchema,
   collectorObserveArgsSchema,
   collectorOutputArgsSchema,
   collectorReadArgsSchema,
@@ -76,6 +83,7 @@ export class CollectorTargetBindError extends CorrectableSubmissionError {
 
 export {
   COLLECTOR_BIND_TARGET_TOOL,
+  COLLECTOR_HANDBOOK_WRITE_TOOL,
   COLLECTOR_OBSERVE_TOOL,
   COLLECTOR_OUTPUT_TOOL,
   COLLECTOR_READ_TOOL,
@@ -89,6 +97,7 @@ export const COLLECTOR_REQUIRED_TOOLS = [
   COLLECTOR_READ_TOOL,
   COLLECTOR_REQUEST_TOOL,
   COLLECTOR_WAIT_TOOL,
+  COLLECTOR_HANDBOOK_WRITE_TOOL,
   COLLECTOR_OUTPUT_TOOL,
 ] as const;
 
@@ -125,12 +134,14 @@ const readSchema = collectorReadArgsSchema;
 const requestSchema = collectorRequestArgsSchema;
 const waitSchema = collectorWaitArgsSchema;
 const bindSchema = collectorBindTargetArgsSchema;
+const handbookWriteSchema = collectorHandbookWriteArgsSchema;
 const outputSchema = collectorOutputArgsSchema;
 
 type RequestParams = Static<typeof requestSchema>;
 type ReadParams = Static<typeof readSchema>;
 type WaitParams = Static<typeof waitSchema>;
 type BindParams = Static<typeof bindSchema>;
+type HandbookWriteParams = Static<typeof handbookWriteSchema>;
 type OutputParams = Static<typeof outputSchema>;
 
 export type CollectorRoleDependencies = {
@@ -138,6 +149,8 @@ export type CollectorRoleDependencies = {
   createTransport(): CollectorGitHubTransport;
   createClock?(): CollectorClock;
   createLedger(config: CollectorConfigState, clock: CollectorClock, ctx: HostContext): CollectorLedger;
+  /** Optional packaged seed for first-use general handbook (#677). */
+  loadHandbookSeed?(): Promise<string>;
 };
 
 export type CollectorRoleHostActions = {
@@ -151,25 +164,51 @@ export type CollectorActivation = {
   ledger: CollectorLedger;
   transport: CollectorGitHubTransport;
   clock: CollectorClock;
+  handbook: CollectorHandbookStore;
+  /** Loaded at activate; refreshed after handbook write for same-session materials. */
+  handbookView: {
+    general: string;
+    repo: string;
+    generalSource: "book" | "seed" | "empty";
+    repoSource: "book" | "empty";
+    generalPath: string;
+    repoPath: string;
+  };
 };
 
 function buildMethodContext(activation: CollectorActivation): string {
   const pr = activation.ledger.config.prNumber;
-  return [
+  const handbook = activation.handbookView;
+  const lines = [
     "<collector_method>",
     `host: github.com`,
     `repository: ${activation.repository.canonical}`,
-    `prNumber: ${pr === undefined ? "unbound — call ak_collector_bind_target with the role-decided issue/PR before observe" : String(pr)}`,
+    `prNumber: ${pr === undefined ? "未绑定" : String(pr)}`,
     `requests: ${JSON.stringify(activation.manifest.requests.map((request) => ({ id: request.id })))}`,
+    `handbookGeneralSource: ${handbook.generalSource}`,
+    `handbookRepoSource: ${handbook.repoSource}`,
     "</collector_method>",
-  ].join("\n");
+  ];
+  // Opaque working memory only — no directional instructions (ADR 0073).
+  // JSON + `<` → \u003c keeps bodies from forging the delivery close tag (#677).
+  if (handbook.general.length > 0 || handbook.repo.length > 0) {
+    const payload = JSON.stringify({
+      general: handbook.general,
+      repo: handbook.repo,
+      generalSource: handbook.generalSource,
+      repoSource: handbook.repoSource,
+      repository: activation.repository.canonical,
+    }).replaceAll("<", "\\u003c");
+    lines.push("", "<collector_handbook>", payload, "</collector_handbook>");
+  }
+  return lines.join("\n");
 }
 
 function parsePositiveTicket(raw: unknown, label: string): number | undefined {
   if (raw === undefined || raw === null) return undefined;
   if (typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 1) return raw;
   if (typeof raw === "string" && /^[1-9]\d*$/.test(raw.trim())) return Number(raw.trim());
-  throw new CollectorTargetBindError(`ak_collector_bind_target ${label} must be a positive safe integer`);
+  throw new CollectorTargetBindError(`通进司绑定 ${label} 须为正安全整数`);
 }
 
 /**
@@ -228,6 +267,26 @@ export function createCollectorRoleRuntime(
         ctx,
       );
 
+      // #677: handbook under admitted book topology (session path → books/<key>/collector-handbook).
+      const sessionPath = ctx.sessionManager?.getSessionFile?.()
+        ?? ctx.sessionManager?.getSessionDir?.();
+      if (typeof sessionPath !== "string" || sessionPath.length === 0) {
+        throw new Error("通进司手册要求 session 路径位于 books/<bookKey>/");
+      }
+      const placement = resolveCollectorHandbookRoot(sessionPath);
+      const seedGeneral = dependencies.loadHandbookSeed === undefined
+        ? undefined
+        : (await dependencies.loadHandbookSeed()).trim();
+      const handbook = createCollectorHandbookStore({
+        ledgerHome: placement.ledgerHome,
+        handbookRoot: placement.root,
+        repositoryCanonical: repository.canonical,
+        ...(seedGeneral === undefined || seedGeneral.length === 0
+          ? {}
+          : { seedGeneral }),
+      });
+      const handbookView = await handbook.read();
+
       return {
         soul,
         repository,
@@ -235,6 +294,8 @@ export function createCollectorRoleRuntime(
         ledger,
         transport,
         clock,
+        handbook,
+        handbookView,
       };
     },
 
@@ -297,7 +358,7 @@ export function createCollectorRoleRuntime(
             const issueNumber = parsePositiveTicket(params.issueNumber, "issueNumber");
             if (prNumber === undefined && issueNumber === undefined) {
               throw new CollectorTargetBindError(
-                "ak_collector_bind_target requires role-decided prNumber and/or issueNumber",
+                "通进司绑定须由角色判定 prNumber 与/或 issueNumber",
               );
             }
 
@@ -310,18 +371,18 @@ export function createCollectorRoleRuntime(
               });
               if (associated.length === 0) {
                 throw new CollectorTargetBindError(
-                  `no PR associated with issue #${issueNumber} in ${activation.repository.canonical}; pass an explicit --pr or a different issueNumber`,
+                  `${activation.repository.canonical} 的 issue #${issueNumber} 无关联 PR；请改用明确 --pr 或其他 issueNumber`,
                 );
               }
               if (associated.length > 1) {
                 throw new CollectorTargetBindError(
-                  `multiple PRs associated with issue #${issueNumber}: ${associated.join(", ")}; pass an explicit prNumber or --pr`,
+                  `issue #${issueNumber} 关联多个 PR：${associated.join("、")}；请改用明确 prNumber 或 --pr`,
                 );
               }
               const fromIssue = associated[0]!;
               if (prNumber !== undefined && prNumber !== fromIssue) {
                 throw new CollectorTargetBindError(
-                  `prNumber ${prNumber} conflicts with issue #${issueNumber} association PR ${fromIssue}`,
+                  `prNumber ${prNumber} 与 issue #${issueNumber} 关联 PR ${fromIssue} 冲突`,
                 );
               }
               bound = fromIssue;
@@ -422,8 +483,8 @@ export function createCollectorRoleRuntime(
       pi.registerTool({
         name: COLLECTOR_REQUEST_TOOL,
         label: "通进司请求",
-        description: "按配置请求体与关联标记，在所引最新快照 HEAD 发一次请求。",
-        promptSnippet: "按配置发一次请求",
+        description: "在所引最新快照 HEAD 发一次请求。requestId 可取配置清单，或角色依手册/现场判定的稳定 id；后者须同时提供 body。",
+        promptSnippet: "发一次评审请求",
         parameters: requestSchema,
         async execute(toolCallId: string, params: RequestParams, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
           const activation = getActivation();
@@ -431,7 +492,11 @@ export function createCollectorRoleRuntime(
           try {
             activation.ledger.beginOperational(COLLECTOR_REQUEST_TOOL, toolCallId);
             const details = await activation.ledger.request(
-              params,
+              {
+                requestId: params.requestId,
+                snapshotId: params.snapshotId,
+                ...(typeof params.body === "string" ? { body: params.body } : {}),
+              },
               activation.transport,
               activation.clock,
               signal,
@@ -451,6 +516,47 @@ export function createCollectorRoleRuntime(
         },
       });
 
+      pi.registerTool({
+        name: COLLECTOR_HANDBOOK_WRITE_TOOL,
+        label: "通进司手册写入",
+        description: "写入通用手册或当前仓库差异全文（整份替换）。",
+        promptSnippet: "更新 bot 手册",
+        parameters: handbookWriteSchema,
+        async execute(toolCallId: string, params: HandbookWriteParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext) {
+          const activation = getActivation();
+          if (activation === undefined) throw new Error("通进司未激活");
+          try {
+            activation.ledger.beginOperational(COLLECTOR_HANDBOOK_WRITE_TOOL, toolCallId);
+            // scope/body shape authority = collectorHandbookWriteArgsSchema (host parameters).
+            const details = await activation.handbook.write(params.scope, params.body);
+            activation.handbookView = await activation.handbook.read();
+            activation.ledger.completeOperational(toolCallId);
+            return {
+              content: [{
+                type: "text" as const,
+                text: `手册已写入：${details.scope}`,
+              }],
+              details: {
+                scope: details.scope,
+                path: details.path,
+                byteLength: details.byteLength,
+                generalSource: activation.handbookView.generalSource,
+                repoSource: activation.handbookView.repoSource,
+              },
+            };
+          } catch (error) {
+            if (isCorrectableExecuteError(error)) throw error;
+            hostActions.failInfrastructure(error, ctx, toolCallId);
+          } finally {
+            try {
+              activation.ledger.completeOperational(toolCallId);
+            } catch {
+              // already completed or not begun
+            }
+          }
+        },
+      });
+
       pi.registerTool({
         name: COLLECTOR_WAIT_TOOL,
         label: "通进司等待",