@fitlab-ai/agent-infra 0.5.9 → 0.6.0

package/lib/sandbox/shell.ts

@@ -0,0 +1,186 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { ExecFileSyncOptions, StdioOptions, SpawnSyncOptions, SpawnSyncReturns } from 'node:child_process';
+
+const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
+
+type CommandOptions = {
+  cwd?: string;
+  encoding?: BufferEncoding;
+  stdio?: StdioOptions;
+  timeout?: number;
+  shell?: boolean;
+};
+
+type RunProbeOptions = CommandOptions & {
+  spawnFn?: typeof spawnSync;
+};
+
+function normalizeOptions(opts: CommandOptions = {}, stdio: StdioOptions): CommandOptions {
+  return {
+    cwd: opts.cwd,
+    encoding: opts.encoding,
+    stdio,
+    timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS
+  };
+}
+
+function resolveCommand(cmd: string): string {
+  if (process.platform !== 'win32' || path.extname(cmd)) {
+    return cmd;
+  }
+
+  const pathValue = process.env.Path || process.env.PATH || '';
+  const extensions = (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+    .split(';')
+    .filter(Boolean);
+
+  for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = path.join(dir, `${cmd}${extension.toLowerCase()}`);
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+      const upperCandidate = path.join(dir, `${cmd}${extension.toUpperCase()}`);
+      if (fs.existsSync(upperCandidate)) {
+        return upperCandidate;
+      }
+    }
+  }
+
+  return cmd;
+}
+
+function commandOptions<T extends CommandOptions>(cmd: string, opts: T): T | (T & { shell: true }) {
+  if (process.platform === 'win32' && /\.(?:bat|cmd)$/i.test(cmd)) {
+    return { ...opts, shell: true };
+  }
+  return opts;
+}
+
+export function run(cmd: string, args: string[], opts: CommandOptions = {}): string {
+  const resolved = resolveCommand(cmd);
+  return execFileSync(resolved, args, commandOptions(resolved, {
+    ...normalizeOptions(opts, ['pipe', 'pipe', 'pipe']),
+    encoding: 'utf8'
+  })).trim();
+}
+
+export function runOk(cmd: string, args: string[], opts: CommandOptions = {}): boolean {
+  const resolved = resolveCommand(cmd);
+  const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'pipe')));
+  return result.status === 0;
+}
+
+export function restoreTerminal(): void {
+  if (!process.stdout.isTTY) {
+    return;
+  }
+
+  try {
+    process.stdout.write([
+      '\x1b[?1049l',
+      '\x1b[?25h',
+      '\x1b>',
+      '\x1b[?1000l',
+      '\x1b[?1002l',
+      '\x1b[?1003l',
+      '\x1b[?1006l'
+    ].join(''));
+  } catch {
+    // Best-effort cleanup only; preserve the original command result.
+  }
+
+  if (process.platform === 'win32') {
+    return;
+  }
+
+  try {
+    execFileSync('stty', ['sane'], { stdio: 'inherit' });
+  } catch {
+    // Some environments do not provide stty or reject sane; ANSI reset still helps.
+  }
+}
+
+export function runInteractive(cmd: string, args: string[], opts: CommandOptions = {}): number {
+  const resolved = resolveCommand(cmd);
+  try {
+    const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'inherit')));
+    return result.status ?? 1;
+  } finally {
+    restoreTerminal();
+  }
+}
+
+export function runVerbose(cmd: string, args: string[], opts: CommandOptions = {}): void {
+  const resolved = resolveCommand(cmd);
+  const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'inherit')));
+
+  if (result.status !== 0) {
+    if (result.signal === 'SIGTERM') {
+      throw new Error(`Command timed out after ${opts.timeout ?? DEFAULT_TIMEOUT_MS}ms: ${cmd}`);
+    }
+    throw new Error(`Command failed with exit code ${result.status}: ${cmd}`);
+  }
+}
+
+export function runSafe(cmd: string, args: string[], opts: CommandOptions = {}): string {
+  const resolved = resolveCommand(cmd);
+  const result = spawnSync(resolved, args, commandOptions(resolved, {
+    ...normalizeOptions(opts, ['pipe', 'pipe', 'pipe']),
+    encoding: 'utf8',
+  }));
+  if (result.status !== 0 && result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+  return (result.stdout ?? '').trim();
+}
+
+export function commandForEngine(engine: string, cmd: string, args: string[] = []): { cmd: string; args: string[] } {
+  if (engine === 'wsl2') {
+    const resolvedWrapper = resolveCommand('wsl.exe');
+    return { cmd: resolvedWrapper, args: ['--', cmd, ...args] };
+  }
+
+  return { cmd, args };
+}
+
+export function runEngine(engine: string, cmd: string, args: string[], opts: CommandOptions = {}): string {
+  const command = commandForEngine(engine, cmd, args);
+  return run(command.cmd, command.args, opts);
+}
+
+export function execEngine(engine: string, cmd: string, args: string[], opts: ExecFileSyncOptions = {}) {
+  const command = commandForEngine(engine, cmd, args);
+  return execFileSync(command.cmd, command.args, opts);
+}
+
+export function runOkEngine(engine: string, cmd: string, args: string[], opts: CommandOptions = {}): boolean {
+  const command = commandForEngine(engine, cmd, args);
+  return runOk(command.cmd, command.args, opts);
+}
+
+export function runSafeEngine(engine: string, cmd: string, args: string[], opts: CommandOptions = {}): string {
+  const command = commandForEngine(engine, cmd, args);
+  return runSafe(command.cmd, command.args, opts);
+}
+
+export function runVerboseEngine(engine: string, cmd: string, args: string[], opts: CommandOptions = {}): void {
+  const command = commandForEngine(engine, cmd, args);
+  return runVerbose(command.cmd, command.args, opts);
+}
+
+export function runInteractiveEngine(engine: string, cmd: string, args: string[], opts: CommandOptions = {}): number {
+  const command = commandForEngine(engine, cmd, args);
+  return runInteractive(command.cmd, command.args, opts);
+}
+
+export function runProbe(cmd: string, args: string[], opts: RunProbeOptions = {}): SpawnSyncReturns<string | Buffer> {
+  const { spawnFn = spawnSync, ...commandOpts } = opts;
+  const resolved = resolveCommand(cmd);
+  return spawnFn(resolved, args, commandOptions(resolved, normalizeOptions(
+    { encoding: 'utf8', ...commandOpts },
+    commandOpts.stdio ?? ['pipe', 'pipe', 'pipe']
+  )));
+}

package/lib/sandbox/{task-resolver.js → task-resolver.ts}

@@ -4,11 +4,11 @@ import path from 'node:path';
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const WORKSPACE_DIRS = ['active', 'completed', 'blocked', 'archive'];
 
-function stripQuotes(value) {
+function stripQuotes(value: string): string {
   return value.replace(/^(["'])(.*)\1$/, '$2');
 }
 
-function readTaskContent(repoRoot, taskId) {
+function readTaskContent(repoRoot: string, taskId: string): string {
   for (const dir of WORKSPACE_DIRS) {
     const taskPath = path.join(repoRoot, '.agents', 'workspace', dir, taskId, 'task.md');
     if (fs.existsSync(taskPath)) {
@@ -18,21 +18,21 @@ function readTaskContent(repoRoot, taskId) {
   throw new Error(`Task not found: ${taskId}`);
 }
 
-function resolveBranchFromTaskContent(content, taskId) {
+function resolveBranchFromTaskContent(content: string, taskId: string): string {
   const frontmatterBranch = content.match(/^branch:\s*(.+)$/m);
-  if (frontmatterBranch && frontmatterBranch[1].trim()) {
+  if (frontmatterBranch?.[1]?.trim()) {
     return stripQuotes(frontmatterBranch[1].trim());
   }
 
   const contextBranch = content.match(/^- \*\*(?:分支|Branch)\*\*：[ \t]*`?([^`\n]+)`?$/m);
-  if (contextBranch && contextBranch[1].trim()) {
+  if (contextBranch?.[1]?.trim()) {
     return stripQuotes(contextBranch[1].trim());
   }
 
   throw new Error(`Task ${taskId} has no branch field in task.md`);
 }
 
-export function resolveTaskBranch(arg, repoRoot) {
+export function resolveTaskBranch(arg: string, repoRoot: string): string {
   if (!TASK_ID_RE.test(arg)) {
     return arg;
   }

package/lib/sandbox/{tools.js → tools.ts}

@@ -1,29 +1,29 @@
-import path from 'node:path';
-import { safeNameCandidates, sanitizeBranchName } from './constants.js';
+import { safeNameCandidates, sanitizeBranchName } from './constants.ts';
+import { hostJoin } from './engines/wsl2-paths.ts';
 
-/**
- * @typedef {Object} SandboxTool
- * @property {string} id
- * @property {string} name
- * @property {string} npmPackage
- * @property {string} sandboxBase
- * @property {string} containerMount
- * @property {string} versionCmd
- * @property {string} setupHint
- * @property {Record<string, string>=} envVars
- * @property {Array<{ hostPath: string, sandboxName: string }>=} hostPreSeedFiles
- * @property {Array<{ hostDir: string, sandboxSubdir: string }>=} hostPreSeedDirs
- * @property {string[]=} pathRewriteFiles
- * @property {Array<{ hostPath: string, containerSubpath: string }>=} hostLiveMounts
- * @property {string[]=} postSetupCmds
- */
+export type SandboxTool = {
+  id: string;
+  name: string;
+  npmPackage: string;
+  sandboxBase: string;
+  containerMount: string;
+  versionCmd: string;
+  setupHint: string;
+  envVars?: Record<string, string>;
+  hostPreSeedFiles?: Array<{ hostPath: string; sandboxName: string }>;
+  hostPreSeedDirs?: Array<{ hostDir: string; sandboxSubdir: string }>;
+  pathRewriteFiles?: string[];
+  hostLiveMounts?: Array<{ hostPath: string; containerSubpath: string }>;
+  postSetupCmds?: string[];
+};
 
-function hostJoin(basePath, ...segments) {
-  return basePath.startsWith('/') ? path.posix.join(basePath, ...segments) : path.join(basePath, ...segments);
-}
+type ToolsConfig = {
+  home: string;
+  project: string;
+  tools: string[];
+};
 
-function createBuiltinTools(home, project) {
-  /** @type {Record<string, SandboxTool>} */
+function createBuiltinTools(home: string, project: string): Record<string, SandboxTool> {
   return {
     'claude-code': {
       id: 'claude-code',
@@ -78,6 +78,10 @@ function createBuiltinTools(home, project) {
       containerMount: '/home/devuser/.local/share/opencode',
       versionCmd: 'opencode version',
       setupHint: 'Configure OpenCode credentials inside the container before first use.',
+      // OpenCode reads opencode.json from $XDG_CONFIG_HOME/opencode by default,
+      // outside this tool mount. Pin the config file path so the inherited
+      // sandbox opencode.json is the one the TUI actually reads.
+      envVars: { OPENCODE_CONFIG: '/home/devuser/.local/share/opencode/opencode.json' },
       hostLiveMounts: [
         {
           hostPath: hostJoin(home, '.local', 'share', 'opencode', 'auth.json'),
@@ -104,13 +108,13 @@ function createBuiltinTools(home, project) {
   };
 }
 
-function validateTool(tool) {
+function validateTool(tool: SandboxTool): void {
   if (!tool.npmPackage || !tool.containerMount.startsWith('/')) {
     throw new Error(`Invalid sandbox tool descriptor: ${tool.id}`);
   }
 }
 
-export function resolveTools(config) {
+export function resolveTools(config: ToolsConfig): SandboxTool[] {
   const builtins = createBuiltinTools(config.home, config.project);
   return config.tools.map((id) => {
     const tool = builtins[id];
@@ -122,18 +126,18 @@ export function resolveTools(config) {
   });
 }
 
-export function toolConfigDir(tool, project, branch) {
+export function toolConfigDir(tool: SandboxTool, project: string, branch: string): string {
   return hostJoin(tool.sandboxBase, project, sanitizeBranchName(branch));
 }
 
-export function toolConfigDirCandidates(tool, project, branch) {
+export function toolConfigDirCandidates(tool: SandboxTool, project: string, branch: string): string[] {
   return safeNameCandidates(branch).map((name) => hostJoin(tool.sandboxBase, project, name));
 }
 
-export function toolProjectDirCandidates(tool, project) {
+export function toolProjectDirCandidates(tool: SandboxTool, project: string): string[] {
   return [hostJoin(tool.sandboxBase, project)];
 }
 
-export function toolNpmPackagesArg(tools) {
+export function toolNpmPackagesArg(tools: SandboxTool[]): string {
   return tools.map((tool) => tool.npmPackage).join(' ');
 }

package/lib/{update.js → update.ts}

@@ -1,18 +1,41 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { info, ok, err } from './log.js';
-import { resolveTemplateDir } from './paths.js';
-import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.js';
+import { info, ok, err } from './log.ts';
+import { resolveTemplateDir } from './paths.ts';
+import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.ts';
+
+type FileRegistry = {
+  managed: string[];
+  merged: string[];
+  ejected: string[];
+};
+
+type UpdateConfig = {
+  project: string;
+  org: string;
+  language: string;
+  platform?: { type?: string };
+  sandbox?: Record<string, unknown>;
+  labels?: Record<string, unknown>;
+  files?: Partial<FileRegistry>;
+};
+
+type Defaults = {
+  platform: { type: string };
+  sandbox: Record<string, unknown>;
+  labels: Record<string, unknown>;
+  files: FileRegistry;
+};
 
 const defaults = JSON.parse(
   fs.readFileSync(new URL('./defaults.json', import.meta.url), 'utf8')
-);
+) as Defaults;
 
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
 
-function isPathOwnedByOtherPlatform(relativePath, platformType) {
-  const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0];
+function isPathOwnedByOtherPlatform(relativePath: string, platformType: string): boolean {
+  const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0] ?? '';
   if (!top.startsWith('.')) return false;
 
   const candidate = top.slice(1);
@@ -20,7 +43,7 @@ function isPathOwnedByOtherPlatform(relativePath, platformType) {
   return candidate !== platformType;
 }
 
-function syncFileRegistry(config, platformType) {
+function syncFileRegistry(config: UpdateConfig, platformType: string) {
   config.files ||= {};
   const before = JSON.stringify({
     files: {
@@ -38,7 +61,7 @@ function syncFileRegistry(config, platformType) {
     ...config.files.merged,
     ...config.files.ejected
   ];
-  const added = { managed: [], merged: [] };
+  const added: Pick<FileRegistry, 'managed' | 'merged'> = { managed: [], merged: [] };
 
   for (const entry of defaults.files.managed) {
     if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
@@ -66,7 +89,7 @@ function syncFileRegistry(config, platformType) {
   return { added, changed: before !== after };
 }
 
-async function cmdUpdate() {
+async function cmdUpdate(): Promise<void> {
   console.log('');
   console.log('  agent-infra update');
   console.log('  ==================================');
@@ -90,7 +113,7 @@ async function cmdUpdate() {
   }
 
   // read project config
-  const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+  const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')) as UpdateConfig;
   const { project, org, language } = config;
   const platformType = config.platform?.type || defaults.platform.type;
   const replacements = { project, org };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.5.9",
+  "version": "0.6.0",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -18,16 +18,18 @@
     "registry": "https://registry.npmjs.org/"
   },
   "bin": {
-    "agent-infra": "./bin/cli.js",
-    "ai": "./bin/cli.js"
+    "agent-infra": "./dist/bin/cli.js",
+    "ai": "./dist/bin/cli.js"
   },
   "files": [
-    "bin/cli.js",
+    "dist/",
+    "!dist/**/*.map",
+    "bin/cli.ts",
     "lib/",
     "templates/"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "keywords": [
     "ai",
@@ -41,16 +43,24 @@
     "installer"
   ],
   "dependencies": {
-    "@clack/prompts": "1.2.0",
-    "picocolors": "1.1.1"
+    "@clack/prompts": "1.4.0",
+    "cross-spawn": "^7.0.6",
+    "picocolors": "1.1.1",
+    "smol-toml": "^1.6.1"
   },
   "scripts": {
-    "build": "node scripts/build-inline.js",
+    "build": "tsc -p tsconfig.json && node scripts/build.js && node scripts/build-inline.js",
     "demo:regen": "sh scripts/demo-regen.sh",
     "prepare": "git config core.hooksPath .git-hooks || true",
-    "test:smoke": "node scripts/build-inline.js --check && node --test tests/templates/*.test.js tests/core/airc.test.js tests/core/release.test.js tests/core/metadata-sync-workflow.test.js tests/core/pr-label-workflow.test.js tests/core/status-label-workflow.test.js tests/core/test-tier-coverage.test.js tests/cli/lib.test.js tests/cli/sync-templates.test.js tests/scripts/sync-templates-platform-gating.test.js",
-    "test:core": "node scripts/build-inline.js --check && node --test tests/templates/*.test.js tests/core/airc.test.js tests/core/release.test.js tests/core/metadata-sync-workflow.test.js tests/core/pr-label-workflow.test.js tests/core/status-label-workflow.test.js tests/core/test-tier-coverage.test.js tests/cli/lib.test.js tests/cli/sync-templates.test.js tests/scripts/sync-templates-platform-gating.test.js tests/cli/cli.test.js tests/cli/merge.test.js tests/cli/sandbox.test.js tests/core/custom-skills.test.js tests/core/custom-tuis.test.js tests/core/demo-regen.test.js tests/scripts/find-existing-task.test.js tests/scripts/platform-adapter-defaults.test.js",
-    "test": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js tests/scripts/*.test.js",
-    "prepublishOnly": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js tests/scripts/*.test.js"
+    "typecheck": "tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.jschecks.json --noEmit",
+    "test:smoke": "npm run build && node --experimental-strip-types --no-warnings --test tests/templates/*.test.ts tests/core/airc.test.ts tests/core/release.test.ts tests/core/metadata-sync-workflow.test.ts tests/core/pr-label-workflow.test.ts tests/core/status-label-workflow.test.ts tests/core/test-tier-coverage.test.ts tests/cli/lib.test.ts tests/cli/sync-templates.test.ts tests/scripts/sync-templates-platform-gating.test.ts",
+    "test:core": "npm run build && node --experimental-strip-types --no-warnings --test tests/templates/*.test.ts tests/core/airc.test.ts tests/core/release.test.ts tests/core/metadata-sync-workflow.test.ts tests/core/pr-label-workflow.test.ts tests/core/status-label-workflow.test.ts tests/core/test-tier-coverage.test.ts tests/cli/lib.test.ts tests/cli/sync-templates.test.ts tests/scripts/sync-templates-platform-gating.test.ts tests/cli/cli.test.ts tests/cli/merge.test.ts tests/cli/sandbox.test.ts tests/core/custom-skills.test.ts tests/core/custom-tuis.test.ts tests/core/demo-regen.test.ts tests/scripts/find-existing-task.test.ts tests/scripts/platform-adapter-defaults.test.ts",
+    "test": "npm run build && node --experimental-strip-types --no-warnings --test tests/cli/*.test.ts tests/templates/*.test.ts tests/core/*.test.ts tests/scripts/*.test.ts",
+    "prepublishOnly": "npm run build && node --experimental-strip-types --no-warnings --test tests/cli/*.test.ts tests/templates/*.test.ts tests/core/*.test.ts tests/scripts/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^22.19.19",
+    "typescript": "~5.9"
   }
 }

package/templates/.agents/rules/create-issue.github.en.md

@@ -155,10 +155,8 @@ Update task.md:
 
 - Write `issue_number: {n}` into the frontmatter (replace if it exists; append at the end of the frontmatter otherwise)
 - Update `updated_at` to the current time (command: `date "+%Y-%m-%d %H:%M:%S%:z"`)
-- Append to the `## 活动日志` / `## Activity Log` section:
-  ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Create Issue** by {agent} — Created GitHub Issue #{n}
-  ```
+
+> Do NOT append an Activity Log entry here. The Issue creation event is already captured by the GitHub Issue itself and by the frontmatter `issue_number` field; the Activity Log only records the single `create-task` skill execution anchor (`Task Created`), written by the caller SKILL step 3.
 
 ### 8. Return the Result
 

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -155,10 +155,8 @@ gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
 
 - 把 `issue_number: {n}` 写入 frontmatter（已存在则替换；不存在则在 frontmatter 末尾追加）
 - 更新 `updated_at` 为当前时间（命令：`date "+%Y-%m-%d %H:%M:%S%:z"`）
-- 在 `## 活动日志` / `## Activity Log` 段落追加：
-  ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Create Issue** by {agent} — Created GitHub Issue #{n}
-  ```
+
+> 不要在此追加 Activity Log 条目。Issue 创建事件已由 GitHub Issue 自身和 frontmatter `issue_number` 承载；Activity Log 仅记录 `create-task` skill 一次执行的整体锚点（`Task Created`），由调用方 SKILL 步骤 3 写入。
 
 ### 8. 返回结果
 

package/templates/.agents/rules/issue-pr-commands.github.en.md

@@ -120,6 +120,35 @@ Read Issue comments or search for existing hidden markers:
 gh api "repos/$upstream_repo/issues/{issue-number}/comments" --paginate
 ```
 
+## Historical Task Comment Scan
+
+`find-existing-task.js` only consumes stdin and does not call `gh` directly. The AI selects the pipeline command for the host OS.
+
+POSIX (bash / zsh):
+
+```bash
+set -o pipefail
+gh api "repos/$upstream_repo/issues/{issue-number}/comments" \
+  --paginate --jq '.[] | @json' \
+  | node .agents/scripts/find-existing-task.js
+```
+
+Windows (PowerShell 7+ / pwsh):
+
+```powershell
+$ErrorActionPreference = 'Stop'
+gh api "repos/$upstream_repo/issues/{issue-number}/comments" `
+  --paginate --jq '.[] | @json' |
+  node .agents/scripts/find-existing-task.js
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+```
+
+On PowerShell 5.1, explicitly enable UTF-8 stdio first; otherwise the pipe may corrupt multibyte characters:
+
+```powershell
+[Console]::OutputEncoding = $OutputEncoding = [System.Text.UTF8Encoding]::new()
+```
+
 ## PR Template and Metadata Helpers
 
 Read a repository PR template when present:

package/templates/.agents/rules/issue-pr-commands.github.zh-CN.md

@@ -120,6 +120,35 @@ gh issue close {issue-number} -R "$upstream_repo" --reason "{reason}"
 gh api "repos/$upstream_repo/issues/{issue-number}/comments" --paginate
 ```
 
+## 历史任务评论扫描
+
+`find-existing-task.js` 仅消费 stdin，不直接调用 `gh`。由 AI 按宿主 OS 选择下面的 pipeline 命令。
+
+POSIX（bash / zsh）：
+
+```bash
+set -o pipefail
+gh api "repos/$upstream_repo/issues/{issue-number}/comments" \
+  --paginate --jq '.[] | @json' \
+  | node .agents/scripts/find-existing-task.js
+```
+
+Windows（PowerShell 7+ / pwsh）：
+
+```powershell
+$ErrorActionPreference = 'Stop'
+gh api "repos/$upstream_repo/issues/{issue-number}/comments" `
+  --paginate --jq '.[] | @json' |
+  node .agents/scripts/find-existing-task.js
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+```
+
+在 PowerShell 5.1 上需先显式启用 UTF-8 stdio，否则 pipe 可能损坏多字节字符：
+
+```powershell
+[Console]::OutputEncoding = $OutputEncoding = [System.Text.UTF8Encoding]::new()
+```
+
 ## PR 模板与元数据辅助命令
 
 存在仓库 PR 模板时读取：