Claude代码工作流引擎：CLI驱动的本地化模板执行协议栈

1. 项目概述：这不是一个“模板库”，而是一套可执行的 Claude 代码工作流引擎

“claude-code-templates”这个名称极具迷惑性——它听起来像是一堆静态的.js或.py文件，放在 GitHub 上供人下载、复制、粘贴。但如果你真这么理解，接下来的十分钟就会在npm install报错、codex cli找不到二进制、401 unauthorized和unsupported_country_region_territory这三类错误里反复横跳。我试过三次重装 Node.js、两次重配 Windows 虚拟机平台、一次在 Ubuntu 子系统里编译失败后直接格式化了 WSL2 镜像。最后才明白：claude-code-templates的本质，是一个 CLI 驱动的、面向开发者本地工作流的代码生成协议栈，它的“模板”不是文本文件，而是可参数化、可组合、可调试的执行单元。它解决的核心问题，是把 Claude 的推理能力从网页对话框里“解放”出来，嵌入到你写代码的每一秒里——比如你在 VS Code 里选中一段脏代码，按下快捷键，3 秒内就拿到带完整单元测试、TypeScript 类型注解、JSDoc 文档和 ESLint 兼容修复建议的重构版本；又比如你输入npx claude-code --init api --lang rust --auth jwt，它会自动生成一个符合 OpenAPI 3.1 规范的 Rust Axum 服务骨架，连 Dockerfile、CI 流水线 YAML 和本地开发 HTTPS 证书脚本都一并生成。它不替代你思考，但彻底消灭重复劳动。适合谁？不是初学者照着抄的“模板教程”，而是每天要写 200 行以上业务逻辑、对 CLI 工具链有基本认知（知道npx是什么、PATH怎么配）、能看懂package.json里"bin"字段含义的中高级前端/全栈/基础设施工程师。关键词claude指代其底层模型调用协议，code是输出目标与验证标准，templates是声明式任务定义方式，CLI是交互入口，npm是分发与依赖管理载体——这五个词，缺一不可。

2. 核心设计思路拆解：为什么必须用 CLI + npm + 模板 DSL，而不是浏览器插件或桌面 App？

2.1 拒绝“黑盒 API 调用”：本地化执行层是安全与可控的基石

所有网络热词里反复出现的401 unauthorized、invalid_api_key、country not supported，根源都指向同一个事实：Claude 的官方 API 并非为高频、低延迟、高并发的本地开发场景设计。它默认走的是云服务路由，受地域白名单、IP 频控、API Key 绑定设备等多重限制。如果claude-code-templates简单封装一个fetch()调用，那它就是个脆弱的玩具。真正的设计选择是：所有模板的执行，必须发生在本地 CLI 进程内，且默认不直连 Claude 官方 API。实际架构是三层：第一层是@claude-code/core，一个轻量级运行时，负责解析模板 DSL、管理上下文（当前文件路径、Git 分支、编辑器光标位置）、调度执行器；第二层是@claude-code/adapter，提供抽象的sendPrompt()接口，官方适配器（如claude-adapter-anthropic）仅作为可选插件存在，用户可自由切换为本地 Ollama 模型、LM Studio 服务、甚至自建的 vLLM 推理端点；第三层才是模板本身——它们是纯 JavaScript 函数，接收context对象（含代码片段、语言类型、用户指令），返回结构化CodeResult（含生成代码、diff 补丁、测试用例、安全扫描结果）。这意味着，当你运行npx claude-code --template refactor --target ./src/utils/date.js时，CLI 先读取date.js内容，注入到模板函数的context.code中，再调用你配置的本地模型服务，整个过程不经过任何第三方服务器。我实测过，在断网状态下，用ollama run qwen2:7b作为后端，refactor模板仍能稳定输出符合 ESLint@typescript-eslint/restrict-template-expressions规则的重构建议——这才是开发者真正需要的“离线可用性”。

2.2 模板即代码：DSL 设计为何放弃 YAML/JSON，坚持用 TypeScript 编写？

热搜词里频繁出现pre 标签内,一般都有哪些子标签,例如 code xmp，这暴露了一个关键误解：很多人以为模板是 HTML 片段或 Markdown 示例。实际上，claude-code-templates的模板是.ts文件，导出一个符合TemplateFunction类型的函数。例如最基础的hello-world.ts：

import { TemplateFunction, CodeResult } from '@claude-code/core'; export const template: TemplateFunction = async (context) => { // context 包含：code（选中文本）、language（如 'typescript'）、filePath、selectionRange 等 const prompt = `你是一个资深 ${context.language} 工程师。请为以下代码生成一个简洁、准确的 JSDoc 注释，要求： - 使用 @param 描述每个参数 - 使用 @returns 描述返回值 - 使用 @throws 描述可能抛出的错误 - 保持原有代码风格，不修改逻辑 代码： \`\`\`${context.language} ${context.code} \`\`\``; // 此处调用 adapter.sendPrompt(prompt)，返回模型响应 const response = await context.adapter.sendPrompt(prompt); // 关键：模板必须自己解析响应，生成结构化结果 const jsdocMatch = response.match(/\/\*\*[\s\S]*?\*\//); if (!jsdocMatch) throw new Error('Failed to extract JSDoc'); return { code: `${jsdocMatch[0]}\n${context.code}`, // 合并 JSDoc 与原代码 diff: `+ ${jsdocMatch[0]}\n${context.code}`, // 供 IDE 显示差异 metadata: { template: 'hello-world', version: '1.0.0' } } as CodeResult; };

为什么不用 YAML？因为 YAML 无法表达逻辑分支。比如refactor模板需要判断：如果context.code包含for (let i = 0; i < arr.length; i++)，则优先推荐for...of；如果包含arr.map(x => x * 2)且arr是number[]，则检查是否可替换为TypedArray。这种条件判断，YAML 只能写死规则，而 TypeScript 模板可以调用任意本地函数（如isNumberArray(arr)）、读取项目tsconfig.json、甚至执行tsc --noEmit --dry获取类型信息。我曾为一个金融项目定制模板，它会自动分析context.code中的数值计算，调用mathjs库验证浮点精度风险，并在CodeResult.warnings中插入{"level": "high", "message": "检测到 0.1 + 0.2 计算，建议使用 decimal.js"}。这种深度集成，是任何声明式配置格式都无法企及的。

2.3 CLI 作为唯一入口：为何拒绝 GUI、VS Code 插件等“更友好”的方案？

热词列表里vscode配置claude code、claude desktop高频出现，说明用户渴望无缝集成。但claude-code-templates坚持 CLI 为唯一官方入口，理由很务实：CLI 是唯一能跨编辑器、跨操作系统、跨项目结构保持行为一致的接口。VS Code 插件依赖vscodeAPI，WebStorm 用户怎么办？桌面版需打包 Electron，体积暴涨 80MB，启动慢，更新麻烦。而 CLI 命令npx claude-code --template test --file src/api/user.test.ts，在 VS Code 的终端、iTerm2、Windows Terminal、甚至 Git Bash 里，行为完全一致。更重要的是，CLI 天然支持管道（pipe）和重定向。你可以这样写：

# 从 git diff 获取待审查代码，交给模板处理 git diff HEAD~1 -- src/components/ | npx claude-code --template security-audit --lang jsx > audit-report.md # 将生成的代码直接写入文件，跳过手动复制 npx claude-code --template component --name Header --lang tsx | tee src/components/Header.tsx

这种 Unix 哲学式的组合能力，GUI 根本无法提供。我团队用它构建了自动化 PR 检查流水线：当 PR 提交时，CI 脚本自动运行claude-code --template unit-test为新增代码生成 Jest 测试，覆盖率不足 80% 的 PR 直接被拒绝合并。这个流程在 GitHub Actions、GitLab CI、Jenkins 上零修改复用——因为底层全是 CLI 命令。所谓“友好”，不是点击几下，而是让工具消失在你的工作流里，成为呼吸般自然的存在。

3. 核心细节解析与实操要点：从零搭建可运行环境的关键陷阱与绕过方案

3.1 npm 安装阶段：为什么npm install -g claude-code会失败？三个致命雷区详解

几乎所有新手卡在第一步：npm install -g claude-code报错。热搜词里npm : 无法加载文件 d:\program files\nodejs\npm.ps1,因为在此系统上禁止运行脚本和npm : 无法将“npm”项识别为 cmdlet就是典型症状。这不是claude-code的 bug，而是 npm 与 Windows PowerShell 安全策略的冲突。根本原因在于：npm 的全局安装脚本（npm.ps1）被 Windows 默认策略标记为“不受信任”，PowerShell 拒绝执行。解决方案不是降低安全等级，而是绕过 PowerShell：

提示：永远不要执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser！这会永久降低系统安全性。正确做法是强制 npm 使用cmd.exe而非 PowerShell。

实操步骤：

1. 以管理员身份打开Windows Terminal（非 PowerShell），选择Command Prompt标签页；
2. 运行where npm确认 npm 路径（通常是C:\Program Files\nodejs\npm.cmd）；
3. 执行npm config set script-shell "C:\\Windows\\System32\\cmd.exe"，强制 npm 使用 cmd；
4. 再运行npm install -g claude-code，此时会调用npm.cmd，完美避开 PowerShell 策略。

对于 macOS/Linux 用户，常见问题是npm WARN deprecated node-domexception@1.0.0。这不是错误，而是警告：node-domexception是一个已废弃的 polyfill，claude-code的某些模板（如处理 HTML 字符串的）依赖它。不要试图npm install node-domexception来消除警告——这会导致模板运行时ReferenceError: DOMException is not defined。正确做法是忽略该警告，或在项目根目录创建.npmrc文件，添加ignore-scripts=true（但需确保你不需要模板中的脚本执行能力）。

3.2 模板初始化：npx claude-code --init生成的不是“项目”，而是“工作区配置”

运行npx claude-code --init后，你会得到一个claude-code.config.ts文件。很多人误以为这是类似create-react-app的项目脚手架，其实它只是 CLI 的配置中心。其核心字段解析如下：

// claude-code.config.ts import { ClaudeCodeConfig } from '@claude-code/core'; const config: ClaudeCodeConfig = { // adapter 配置：决定模型后端 adapter: { type: 'ollama', // 可选 'anthropic', 'openai', 'local' options: { host: 'http://localhost:11434', // Ollama 服务地址 model: 'qwen2:7b' // 模型名，必须已通过 `ollama pull qwen2:7b` 下载 } }, // templates 配置：定义可用模板及其别名 templates: [ { id: 'refactor-js', // 模板唯一 ID path: './templates/refactor.ts', // 本地路径，或 npm 包名如 '@myorg/templates/refactor' alias: ['refactor', 'rf'] // 命令行中可用 `--template refactor` 或 `--template rf` } ], // context 扩展：向所有模板注入额外信息 contextExtensions: [ { name: 'gitBranch', fn: () => require('child_process').execSync('git branch --show-current').toString().trim() } ] }; export default config;

关键细节：templates.path支持绝对路径、相对路径（相对于配置文件）、以及 npm 包名。这意味着你可以把公司内部的合规检查模板发布为私有 npm 包@acme/internal-templates，然后在配置中写path: '@acme/internal-templates/security-scan'。CLI 会自动require()它，无需手动npm install。我司就用此机制，将 PCI-DSS 合规代码扫描模板作为私有包分发，所有工程师npx claude-code --template security-scan即可执行，且模板更新时只需npm update @acme/internal-templates，无需修改任何配置。

3.3 模板编写规范：一个合格的.ts模板文件必须包含的四个强制部分

不是所有.ts文件都能被claude-code识别为模板。它遵循严格的约定：文件必须导出一个名为template的常量，且其类型必须是TemplateFunction。一个最小可行模板（MVP Template）必须包含以下四部分：

1. 导入声明（Import Declaration）：必须导入@claude-code/core中的TemplateFunction和CodeResult类型。这是类型安全的基石，也是 CLI 解析模板的标识。

   import { TemplateFunction, CodeResult } from '@claude-code/core';

2. 上下文校验（Context Validation）：模板必须主动检查context是否满足要求。例如test模板要求context.language必须是'javascript'或'typescript'，否则抛出Error('Unsupported language')。CLI 会捕获此错误并友好提示，而非崩溃。

   export const template: TemplateFunction = async (context) => { if (!['javascript', 'typescript'].includes(context.language)) { throw new Error(`Language '${context.language}' not supported for test generation`); } // ... rest of logic };

3. 模型提示工程（Prompt Engineering）：提示词（prompt）不是随意拼接的字符串。它必须包含明确的角色设定（You are a senior X engineer）、具体的任务指令（Generate exactly one test case）、严格的格式约束（Output ONLY valid JSON with keys: "testCode", "assertions"）和防幻觉指令（If uncertain, output {"error": "insufficient_context"}）。我测试过，没有格式约束的 prompt，模型输出Here's a test:开头的自然语言描述，导致模板解析失败率高达 65%；加入Output ONLY valid JSON后，成功率提升至 98.2%。

4. 结构化结果构造（Structured Result Construction）：return语句必须返回一个符合CodeResult接口的对象。CodeResult强制要求code（最终代码字符串）和metadata（模板元数据），可选diff（用于 IDE 预览）、warnings（安全/性能警告）、tests（生成的测试用例数组）。切记：不要直接return response！必须解析模型输出，提取有效内容。例如，若模型返回：

   {"testCode": "it('should handle empty array', () => { expect(process([])).toBeNull(); });", "assertions": ["process([]) returns null"]}

   模板需做：

   const parsed = JSON.parse(response); return { code: parsed.testCode, metadata: { template: 'unit-test', generatedAt: new Date().toISOString() }, tests: [parsed.testCode] };

4. 实操过程与核心环节实现：从配置到生成，一个真实工作流的完整记录

4.1 环境准备：在 Windows 11 上启用虚拟机平台与 WSL2（claude's workspace requires the virtual machine platform on windows的终极解法）

热搜词claude's workspace requires the virtual machine platform on windows. enable直接指向 Windows 系统级依赖。claude-code-templates本身不依赖 VM，但其推荐的本地模型后端（Ollama、LM Studio）需要 Windows Hypervisor Platform (WHPX) 或 Windows Subsystem for Linux (WSL2)。以下是经我实测、100% 成功的启用步骤（无需重启）：

1. 以管理员身份运行 PowerShell（注意：此处必须用 PowerShell，因为dism命令在 cmd 中不可用）；
2. 启用虚拟机平台：

   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

3. 启用 WSL：

   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

4. 下载并安装 WSL2 内核更新包（关键！很多教程遗漏此步）：
   • 访问 https://aka.ms/wsl2kernel
   • 下载wsl_update_x64.msi并双击安装；
5. 设置 WSL2 为默认版本：

   wsl --set-default-version 2

6. 安装 Ubuntu 22.04（从 Microsoft Store）；
7. 在 Ubuntu 中安装 Ollama：

   curl -fsSL https://ollama.com/install.sh | sh

8. 拉取模型：

   ollama pull qwen2:7b

注意：dism命令执行后，系统会提示“操作成功完成”，但此时并未生效。必须安装 WSL2 内核更新包并重启电脑，否则wsl --list --verbose会显示VERSION为空。我踩过的坑是跳过第4步，导致ollama serve启动后立即崩溃，日志显示failed to start server: listen tcp 127.0.0.1:11434: bind: address already in use—— 实际是 WHPX 未启用，Ollama 无法绑定端口。

4.2 配置claude-code.config.ts：为refactor模板定制 TypeScript 重构规则

我们以一个真实需求为例：团队要求所有Array.prototype.map()调用，若回调函数只做属性访问（如items.map(i => i.name)），必须重构为items.map(({name}) => name)。这是一个典型的“模式匹配 + 代码生成”任务，完美契合模板能力。

步骤一：创建模板文件templates/refactor-map.ts

import { TemplateFunction, CodeResult } from '@claude-code/core'; import * as acorn from 'acorn'; // 用于 AST 解析 import { generate } from 'astring'; // 用于 AST 生成 export const template: TemplateFunction = async (context) => { // 1. 解析原始代码为 AST const ast = acorn.parse(context.code, { ecmaVersion: 2022, sourceType: 'module' }); // 2. 查找所有 map 调用 const mapCalls: any[] = []; acorn.walk(ast, { CallExpression(node) { if (node.callee.property?.name === 'map' && node.callee.object?.type === 'MemberExpression') { mapCalls.push(node); } } }); // 3. 对每个 map 调用，检查是否符合重构条件 let modifiedCode = context.code; for (const call of mapCalls) { const arg = call.arguments[0]; if (arg.type === 'ArrowFunctionExpression' && arg.params.length === 1 && arg.body.type === 'MemberExpression') { // 符合条件：i => i.name const paramName = arg.params[0].name; const propName = arg.body.property.name; // 构造新参数：({propName}) const newParam = { type: 'ObjectPattern', properties: [{ type: 'Property', key: { type: 'Identifier', name: propName }, value: { type: 'Identifier', name: propName }, kind: 'init', method: false, shorthand: true }] }; // 构造新 body：propName const newBody = { type: 'Identifier', name: propName }; // 替换 AST arg.params = [newParam]; arg.body = newBody; } } // 4. 生成新代码 const newAst = acorn.parse(generate(ast), { ecmaVersion: 2022, sourceType: 'module' }); const newCode = generate(newAst); return { code: newCode, diff: `--- original\n+++ refactored\n${context.code.split('\n').map((l, i) => `-${l}`).join('\n')}\n${newCode.split('\n').map((l, i) => `+${l}`).join('\n')}`, metadata: { template: 'refactor-map', version: '1.0.0' } } as CodeResult; };

步骤二：更新claude-code.config.ts

import { ClaudeCodeConfig } from '@claude-code/core'; const config: ClaudeCodeConfig = { adapter: { type: 'ollama', options: { host: 'http://localhost:11434', model: 'qwen2:7b' } }, templates: [ { id: 'refactor-map', path: './templates/refactor-map.ts', alias: ['refactor-map', 'rm'] } ] }; export default config;

步骤三：执行重构

# 创建测试文件 echo "const items = [{name: 'Alice'}, {name: 'Bob'}]; const names = items.map(i => i.name);" > test.ts # 运行模板 npx claude-code --template refactor-map --file test.ts # 输出结果（已自动应用） # const items = [{name: 'Alice'}, {name: 'Bob'}]; const names = items.map(({name}) => name);

这个例子展示了模板的真正威力：它不是调用大模型“猜”怎么改，而是结合本地 AST 解析（100% 精确匹配模式）与模型能力（处理复杂逻辑分支），实现了确定性重构。模型在这里的作用是兜底——当 AST 解析无法覆盖的边缘 case（如动态属性名），才由模型生成建议。

4.3 集成到 VS Code：用 Task Runner 实现“选中即重构”，告别手动命令行

虽然 CLI 是核心，但日常开发中，没人愿意反复切到终端。VS Code 的 Tasks 功能可以完美桥接。在项目根目录创建.vscode/tasks.json：

{ "version": "2.0.0", "tasks": [ { "label": "Claude: Refactor Map", "type": "shell", "command": "npx claude-code --template refactor-map --file ${file} --selection ${selectedText}", "args": [], "group": "build", "presentation": { "echo": true, "reveal": "always", "focus": false, "panel": "shared", "showReuseMessage": true, "clear": true }, "problemMatcher": [] } ] }

关键参数说明：

• ${file}：当前打开的文件路径；
• ${selectedText}：编辑器中选中的文本（CLI 会将其注入context.code）；
• --selection：CLI 的内置参数，告诉模板只处理选中区域。

配置完成后，在 VS Code 中：

1. 选中items.map(i => i.name)这段代码；
2. 按Ctrl+Shift+P（Windows）或Cmd+Shift+P（Mac），输入Tasks: Run Task；
3. 选择Claude: Refactor Map；
4. 3 秒后，选中区域自动变为items.map(({name}) => name)。

实操心得：VS Code 的 Tasks 有一个隐藏技巧——按Ctrl+Shift+P后，输入>Tasks: Configure Task，选择Create tasks from template->Others，然后粘贴上面的 JSON。这样可以避免手动创建文件的路径错误。另外，"panel": "shared"确保所有 Claude 任务共享同一个终端面板，避免每次执行都开新窗口，极大提升流畅度。

5. 常见问题与排查技巧实录：来自 17 个真实项目的故障树分析

5.1 错误代码unsupported_country_region_territory：不是网络问题，而是模型后端配置错误

这是热搜词中最高频的错误，但 95% 的情况与“地域限制”无关。根本原因是：你配置了adapter.type: 'anthropic'，但未正确设置ANTHROPIC_API_KEY环境变量，或设置了错误的region参数。claude-code的 Anthropic 适配器会尝试调用https://api.anthropic.com/v1/messages，而该端点确实有地域限制。但绝大多数用户根本不需要用 Anthropic 官方 API！解决方案极其简单：

1. 确认你是否真的需要官方 API：如果你只是想在本地快速测试模板，Ollama/LM Studio 是更优选择（免费、离线、无地域限制）；
2. 如果必须用 Anthropic：不要在claude-code.config.ts中硬编码region。改为在系统环境变量中设置：

   # Linux/macOS export ANTHROPIC_API_KEY="your-key-here" export ANTHROPIC_REGION="us-east-1" # 仅当你的账号在 us-east-1 区域时才设置

   # Windows PowerShell $env:ANTHROPIC_API_KEY="your-key-here" $env:ANTHROPIC_REGION="us-east-1"

3. 验证配置：运行npx claude-code --debug --template hello-world，查看 CLI 输出的Adapter initialized: anthropic和Region: us-east-1是否正确。

排查技巧：在claude-code.config.ts中临时将adapter.type改为'ollama'，如果错误消失，100% 证明是 Anthropic 配置问题，而非网络或地域问题。

5.2 错误unable to locate the codex cli binary or required runtime components：codex cli是过时术语，应统一为claude-code

热搜词中混杂了codex cli、claude cli、claude code cli等多种叫法，这是历史遗留问题。codex是早期内部代号，claude-code是正式名称。当你看到unable to locate the codex cli binary错误，说明你或某个脚本仍在调用旧命令。解决方案：

1. 全局搜索项目：在项目根目录执行grep -r "codex" . --include="*.sh" --include="*.js" --include="*.json"，找到所有引用codex的地方；
2. 统一替换：将npx codex、codex-cli、@codex/cli全部替换为npx claude-code、claude-code、@claude-code/cli；
3. 清理残留：删除全局安装的旧包npm uninstall -g codex-cli；
4. 检查 package.json：确保devDependencies中没有codex-cli，只有@claude-code/cli。

我曾接手一个遗留项目，其 CI 脚本里写着npx codex --template lint，而package.json的scripts里却是"lint": "npx claude-code --template lint"。结果开发机上npx codex因找不到包而报错，CI 却因缓存了旧包而正常运行——这种不一致导致了三天的排查黑洞。

5.3 模板执行缓慢或超时：不是模型慢，而是上下文过大或提示词设计缺陷

当npx claude-code --template refactor卡住超过 30 秒，第一反应是“模型太慢”。但实际排查发现，80% 的案例是context.code过大。claude-code默认将整个文件内容传给模板，如果context.code是一个 5000 行的巨型 React 组件，模型需要处理海量 token，必然超时。

优化方案：

• 客户端截断：在模板中主动截断context.code。例如，refactor模板只处理选中区域，而非整个文件：

  // 在 template 函数开头添加 const MAX_CONTEXT_LENGTH = 2000; // 限制 2000 字符 if (context.code.length > MAX_CONTEXT_LENGTH) { const truncated = context.code.substring(0, MAX_CONTEXT_LENGTH) + '... [TRUNCATED]'; console.warn(`Context too long (${context.code.length} chars), truncating to ${MAX_CONTEXT_LENGTH}`); context.code = truncated; }

• 服务端压缩：配置 Ollama 时，启用num_ctx参数限制上下文长度：

  ollama run qwen2:7b --num_ctx 2048

• 提示词优化：避免模糊指令如Improve this code，改用精确指令Refactor only the function named 'calculateTotal' to use optional chaining, keep all other code unchanged。我测试过，精确指令使模型 token 消耗降低 42%，响应时间从 12s 降至 7s。

5.4npm run build失败：@claude-code/core的 TypeScript 编译配置陷阱

当你把模板作为 npm 包发布时，npm run build报错Cannot find module '@claude-code/core'，这是因为@claude-code/core的package.json中types字段指向dist/index.d.ts，但默认tsc不会生成dist目录。解决方案是在tsconfig.json中显式指定：

{ "compilerOptions": { "outDir": "./dist", "declaration": true, "declarationMap": true, "skipLibCheck": true, "esModuleInterop": true, "forceConsistentCasingInFileNames": true, "moduleResolution": "node", "resolveJsonModule": true, "isolatedModules": true, "strict": true, "noUncheckedIndexedAccess": true, "noImplicitOverride": true, "noPropertyAccessFromIndexSignature": true, "plugins": [ { "name": "@ianvs/prettier-plugin-sort-imports" } ] }, "include": ["./templates/**/*"], "exclude": ["node_modules"] }

关键点：outDir必须与@claude-code/core的types路径匹配，且include必须包含你的模板文件。否则tsc不会编译它们，dist目录为空，导致require()失败。

6. 模板生态扩展：如何发布自己的@myorg/templates私有 npm 包

claude-code-templates的终极价值，在于构建组织级的代码生成知识库。将团队最佳实践固化为可复用、可版本化、可审计的模板，是提升研发效能的核武器。以下是发布私有模板包的完整流程：

6.1 包结构设计：为什么必须包含index.ts和templates/目录？

一个合规的模板包（如@acme/internal-templates）必须有以下结构：

@acme/internal-templates/ ├── package.json ├── index.ts # 主入口，导出所有模板 ├── templates/ # 模板文件存放目录 │ ├── security-scan.ts │ ├── api-contract.ts │ └── i18n-extract.ts └── README.md

index.ts的强制内容：

// index.ts import { TemplateFunction } from '@claude-code/core'; import { template as securityScanTemplate } from './templates/security-scan'; import { template as apiContractTemplate } from './templates/api-contract'; // 必须导出一个对象，key 为模板 ID，value 为 TemplateFunction export const templates = { 'security-scan': securityScanTemplate, 'api-contract': apiContractTemplate }; // 必须导出一个默认函数，用于 CLI 自动发现 export default function getTemplate(id: string): TemplateFunction | undefined { return templates[id as keyof typeof templates]; }

为什么这样设计？claude-codeCLI 在解析templates.path: '@acme/internal-templates'时，会require('@acme/internal-templates')，然后调用其默认导出函数getTemplate(id)。如果包没有默认导出，CLI 会报错Template not found。index.ts中的templates对象则是为了方便其他开发者直接import { templates } from '@acme/internal-templates'进行单元测试。

6.2 发布流程：从npm login到npm publish的七步安全清单

1. 注册私有 registry：如果使用 Verdaccio 或 Nexus，先配置 `.npm