@wdyy/skills 0.1.23 → 0.1.25

package/README.md

@@ -16,22 +16,34 @@ OpenSpec                           单项变更的需求、设计、任务、实
 |---|---|
 | `wdyy-database-standard` | PostgreSQL 18 数据库设计、版本化迁移、数据兼容性与 DDL 校验。 |
 | `wdyy-bug-record` | 手动汇总当前任务已解决的问题，并按模板追加至 `docs/bug_record.md`。 |
-| `wdyy-logging-standard` | 结构化日志、敏感字段移除、traceId、前端异常上报与日志轮转。 |
+| `wdyy-logging-standard` | 访问、应用、安全与审计日志，递归敏感字段净化、W3C trace、前端异常上报、轮转与哈希链校验。 |
 | `wdyy-deployment-standard` | 在 Linux、macOS Docker Desktop 或 Windows Docker Desktop + WSL2/Linux 容器模式中，使用本地基础镜像构建前后端独立镜像，分别导出并统一压缩交付，远程数据库直连并一键部署整个项目栈。 |
 | `wdyy-ui` | 统一医院信息系统页面的布局、清新生命绿配色、医院 Logo、常用组件和响应式行为，不定义业务流程、接口或数据模型。 |
 
 ## 使用方式
 
-安装全局包后，在目标项目根目录执行：
+安装全局包后，先由工程师手工安装或更新 OpenSpec、公共 Skill 与 CodeGraph，再在目标项目根目录执行初始化：
 
 ```bash
 npm install -g @wdyy/skills
+npm install -g @fission-ai/openspec@latest
+npx skills@latest add mattpocock/skills -g --skill grill-me grill-with-docs prototype frontend-design research tdd codebase-design
+npx skills@latest add tt-a1i/archify -g
+npm i -g @colbymchenry/codegraph
 wdyy init
 ```
 
-`wdyy init` 会在系统用户目录 `.agents/skills/` 安装或更新 5 个受管理 Skill，并删除其中旧的 `wdyy-api-standard`，但不在目标项目创建 `.agents/skills/`。它还会执行 `git init`，创建或补齐 `.gitignore` 的 `.env`、`node_modules/`、`venv/`、`.pnpm-store/`、`logs/`、`dist/`、`.DS_Store`、`*.tar.gz` 规则，创建 `src/frontend`、`src/backend`、`database`、`deploy`、`docs`、`scripts`、`tests`，并以相同的“前端、后端、数据库、API、部署”结构创建缺失的 `.env` 与 `.env.example`。默认前端监听 `0.0.0.0:5173`、后端监听 `0.0.0.0:3000`、数据库端口为 `5432`；已有环境文件保持不变。随后命令执行 `openspec init`、创建或追加 `docs/bug_record.md` 模板。若目标项目已有 `AGENTS.md`，原文件保持不变，命令将生成 `AGENTS_new.md`。
+`wdyy init` 启动时会再次显示上述外部依赖安装命令，但不会自动执行 npm 或 npx。命令在写入前集中检查 Node.js 24、pnpm 12.1.0、Git、OpenSpec、CodeGraph，以及规则强制使用的公共 Skill；任一项缺失或版本不符时一次性报告全部问题并退出。
 
-生成的项目规则要求：接口实现仅以工程师人工提供的 YAML 文件为依据；未提供 YAML 或接口契约不完整时必须询问工程师，不得从旧 Skill、reference、远程目录或其他来源推断或编造。既有项目需要重新执行 `wdyy init` 才会生成包含该要求的新规则文件。
+预检通过后，`wdyy init` 会在系统用户目录 `.agents/skills/` 安装或更新 5 个受管理 Skill，并删除其中旧的 `wdyy-api-standard`。它还会初始化 Git、默认目录、环境模板、BUG 模板、OpenSpec 与 CodeGraph。已有环境文件和 BUG 记录保持不变；已有 `AGENTS.md` 时生成 `AGENTS_new.md`。全部步骤成功后生成 `.wdyy/toolchain.json`，记录初始化器与工具版本、实际规则文件以及公共和企业 Skill 的 SHA-256；清单不含用户名、凭据或绝对主目录。
+
+生成规则负责项目边界与 Skill 路由：`grill-me` 澄清需求和验收标准，`grill-with-docs` 记录 PRD、术语与 ADR；文档沉淀完成后先使用 `openspec-explore` 探索方案、约束与风险，再使用 `openspec-propose` 形成可评审计划并进入实施流程。数据库、日志、部署和 UI 的执行细节由对应 Skill 唯一维护。自建接口由 Agent 根据已确认需求生成 OpenAPI 3.1 YAML 并交工程师验收；第三方接口只依据工程师提供的契约或官方文档。
+
+初始化后在项目根目录执行以下只读验收；命令集中检查初始化产物、工具版本、Skill 和工具链清单漂移，不会自动修复文件：
+
+```bash
+wdyy validate
+```
 
 生成的项目规则还要求：每个经确认的变更完成并通过全部测试与验证后创建对应 Git commit，不得提交未完成或验证失败的状态；每个变更依据对应 OpenSpec 的需求、场景和任务编写或更新相关测试，交付前必须解决全部测试与验证失败，不得跳过或隐瞒。既有项目重新执行 `wdyy init` 后，可从新生成的 `AGENTS_new.md` 审阅并合并该规则。
 
@@ -50,7 +62,7 @@ wdyy update-skill --all
 
 部署 Skill 生成的标准流程为：在 Linux、macOS Docker Desktop，或 Windows Docker Desktop + WSL2/Linux 文件系统的项目根目录执行 `./deploy.sh build`，只使用本地已有的 Node、Nginx 基础镜像构建 `<项目名>_frontend:latest` 与 `<项目名>_backend:latest`，分别导出两个镜像 tar，并统一封装为 `deploy/<项目名>-docker.tar.gz`。工程师人工复制并解压该压缩包，在受支持的 Linux engine 上无参数执行 `./deploy.sh` 即校验、加载并整体部署前后端；macOS/arm64 Docker Desktop 可通过禁止拉取的实际目标镜像探针验证并运行 `linux/amd64` 包，而不是仅按 Server 原生架构拒绝。另可执行 `./deploy.sh stop` 和 `./deploy.sh status`。数据库通过 `.env` 直连远程 PostgreSQL，不生成数据库容器；前后端的宿主机与容器端口都来自 `.env`，容器名与镜像 repository 相同，使用 `unless-stopped`，并验证 24 小时制 CST（UTC+8）；日志直接保存在部署根 `logs/`。不支持原生 PowerShell 或 Windows 容器模式。
 
-中大型变更先使用 `/opsx:explore` 或 `/opsx:propose <change-name>`，在方案确认后使用 `/opsx:apply`；完成验证后使用 `/opsx:archive`。涉及数据库、日志、部署或医院信息系统 UI 时，按 `AGENTS.md` 的路由加载相应企业 Skill；接口实现仅依据工程师人工提供的 YAML。所有 URL、端口和 IP 地址从 `.env` 读取，不得硬编码；所有项目管理的日志直接写入项目根目录 `logs/`；生产部署不使用蓝绿发布。不得提交秘密或生产环境 `.env`。项目完成后创建 `README.md`，说明技术栈、目录结构和安装部署。
+中大型变更先使用 `/opsx:explore` 或 `/opsx:propose <change-name>`，在方案确认后使用 `/opsx:apply`；完成验证后使用 `/opsx:archive`。涉及数据库、日志、部署或医院信息系统 UI 时，按 `AGENTS.md` 的路由加载相应企业 Skill。自建接口由 Agent 生成 OpenAPI 3.1 YAML 并交工程师验收，第三方接口依据工程师提供的契约或官方文档。所有 URL、端口和 IP 地址从 `.env` 读取，不得硬编码；不得提交秘密或生产环境 `.env`。项目完成后创建 `README.md`，说明技术栈、目录结构和安装部署。
 
 ## 固定技术栈
 
@@ -71,7 +83,7 @@ wdyy update-skill --all
 
 ### 使用发布脚本
 
-推荐从项目根目录手动运行 `release_npm.sh`。脚本会检查工作区、组织权限、lint 与打包内容，自动执行 `npm version <patch|minor|major>`、`npm publish --access public`；发布成功后等待 15 秒，再一次查询刚发布的确切版本进行 registry 核验。它不会执行登录、浏览器认证或处理认证凭据。
+推荐从项目根目录手动运行 `release_npm.sh`。脚本会检查工作区、组织权限、完整测试、lint 与打包内容，自动执行 `npm version <patch|minor|major>`、`npm publish --access public`；发布成功后等待 15 秒，再一次查询刚发布的确切版本进行 registry 核验。它不会执行登录、浏览器认证或处理认证凭据。
 
 首次运行或登录失效时，先手工登录；脚本检测到未登录也会提示并退出：
 
@@ -116,10 +128,11 @@ npm version patch # 修复或小幅调整
 ```bash
 npm test
 npm run lint
-node --test $(find .well-known/skills -path '*/scripts/*.test.mjs' -print)
 npm pack --dry-run
 ```
 
+`npm test` 会通过索引聚合器执行全部受管理 Skill 声明的测试，新增 Skill 测试无需维护 shell 文件发现命令。
+
 其中 `npm pack --dry-run` 用于确认包内容；应包含 `bin`、`lib`、`.well-known/skills` 与 `README.md`，且不应包含本地环境文件或其他无关文件。
 
 ### 3. 登录并核对组织权限

package/lib/wdyy-cli.js

@@ -1,7 +1,8 @@
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { access, appendFile, cp, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -14,6 +15,26 @@ const managedSkillNames = [
 ];
 
 const removedManagedSkillNames = ['wdyy-api-standard'];
+const packageMetadata = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
+const requiredNodeMajor = Number(packageMetadata.engines.node.match(/\d+/)?.[0]);
+const requiredPnpmVersion = packageMetadata.engines.pnpm;
+const requiredPublicSkillNames = [
+  'grill-me',
+  'grill-with-docs',
+  'prototype',
+  'frontend-design',
+  'research',
+  'tdd',
+  'codebase-design',
+  'archify'
+];
+
+const manualPrerequisiteCommands = [
+  'npm install -g @fission-ai/openspec@latest',
+  'npx skills@latest add mattpocock/skills -g --skill grill-me grill-with-docs prototype frontend-design research tdd codebase-design',
+  'npx skills@latest add tt-a1i/archify -g',
+  'npm i -g @colbymchenry/codegraph'
+];
 
 const defaultProjectDirectories = [
   'src/frontend',
@@ -59,9 +80,13 @@ DB_SCHEMA=api_platform
 
 const defaultProjectLayout = [...defaultProjectDirectories, '.env.example'];
 
-const generatedAgentsContent = `# 企业开发规则
+const generatedAgentsContent = `# 项目开发规则
+
+本项目使用 OpenSpec 及企业 Skill 统一开发规则与流程。所有规则面向 agent 执行；规则未覆盖或不明确时，先询问工程师，不得猜测。
+
+## 固定时区
 
-本项目同时使用OpenSpec及企业 Skill统一开发规则及流程。
+- 全链路统一使用 \`TZ=Asia/Shanghai\` 作为时间基准：日志时间戳、数据库时间、前端时间展示、部署脚本时间验证都必须基于 \`Asia/Shanghai\`，禁止混用其他时区。
 
 ## 固定技术栈
 
@@ -76,39 +101,127 @@ const generatedAgentsContent = `# 企业开发规则
 
 \`.env.example\` 是配置模板。需要本地配置时，必须先手工复制 \`.env.example\` 为 \`.env\`；后续修改配置文件时，必须先修改 \`.env.example\`，再同步修改 \`.env\`。不得将真实密码、密钥或生产配置写入 \`.env.example\`。
 
-项目开发完成后必须创建 \`README.md\`，内容包括项目技术栈、目录结构和安装部署说明。
-
 ## Skill 路由
 
-| 场景 | 必须使用的 Skill |
+| 阶段 / 场景 | 必须使用的 Skill |
 |---|---|
+| 需求澄清 | 使用 \`grill-me\` 消除需求、边界与验收标准中的歧义 |
+| PRD 与决策记录 | 使用 \`grill-with-docs\` 记录 PRD、术语和架构决策 |
+| 方案探索 | \`grill-with-docs\` 完成后，使用 \`openspec-explore\` 探索方案、约束与风险 |
+| 变更规划与实施 | 使用 \`openspec-propose\` 生成可评审计划，确认后使用对应 OpenSpec 实施与归档流程 |
+| 原型设计 | \`prototype\` |
+| 通用前端视觉与交互设计 | \`frontend-design\` |
+| 医院信息系统页面的新建、改造或审查 | \`wdyy-ui\`；不负责定义业务流程、接口或数据模型 |
+| 开发过程 | 按需使用 \`research\`、\`tdd\`、\`codebase-design\` |
+| 架构图、时序图、流程图 | \`archify\`，产出放入 \`docs/\` |
 | PostgreSQL 表、DDL、迁移、数据兼容性 | \`wdyy-database-standard\` |
-| 汇总当前任务已解决的 BUG、漏洞或运行异常 | 手动调用 \`wdyy-bug-record\`，追加写入 \`docs/bug_record.md\` |
-| 结构化日志、traceId、完整原始入参、前端异常上报 | \`wdyy-logging-standard\` |
+| 访问、应用、安全与审计日志、W3C trace、净化后的完整业务参数、前端异常上报 | \`wdyy-logging-standard\` |
 | 统一 Docker 交付、Linux/Mac/Windows WSL2 双镜像、远程数据库与整栈一键部署 | \`wdyy-deployment-standard\` |
-| 医院信息系统页面的新建、改造或审查 | \`wdyy-ui\`；不负责定义业务流程、接口或数据模型 |
+| 汇总当前任务已解决的 BUG、漏洞或运行异常 | 手动调用 \`wdyy-bug-record\`，追加写入 \`docs/bug_record.md\` |
+
+## 文档与目录约定
+
+- 项目开发完成后必须创建 \`README.md\`，内容至少包括：项目简介、目录结构、技术栈、本地测试流程、部署流程、使用的数据库。
+- 所有数据库文档统一放置在 \`database/\` 目录。
+- 架构图、时序图、流程图等其它文档统一放置在 \`docs/\` 目录。
 
 ## 通用边界
 
+- 所有需求必须先完成需求澄清和验收标准确认，再形成 PRD 与必要决策记录；\`grill-with-docs\` 完成后必须先使用 \`openspec-explore\` 探索方案，再使用 \`openspec-propose\` 形成可评审规划。涉及业务、接口、数据库、部署或不可逆决定时，实施前必须由工程师确认规划产物。
 - 项目根目录应提供真实可执行的 \`pnpm dev\`、\`pnpm build\`、\`pnpm test\`、\`pnpm lint\` 命令；\`pnpm dev\` 只负责前后端的启动，不得启动或管理数据库。
 - 生成的接口文档必须符合 OpenAPI 3.1 规范，并声明 \`openapi: 3.1.0\`。
+- 自建接口由 Agent 根据已确认需求生成 OpenAPI 3.1 YAML 契约，经工程师验收后实施。第三方接口仅依据工程师提供的契约或官方接口文档；来源缺失或契约不完整时必须询问工程师，不得推测。
 - 在下载或安装任何项目依赖前，必须先从官方发布渠道确认当前最新稳定版本，并检查该版本及其传递依赖的公开漏洞修复状态。原则上必须使用最新稳定版本；不得使用已过时的依赖，也不得使用存在未修复高危（High/Critical）漏洞的依赖。若最新稳定版本不兼容，或不存在满足安全要求的版本，必须停止安装并报告依赖名称、候选版本、兼容性及漏洞证据，等待工程师确认；不得擅自降级、忽略审计结果或添加豁免。
 - 代码、配置、迁移、测试与部署文件必须以实际实现为准；不得用模板虚构已实现能力。
-- 所有需求（如数据库变更、流程变更、功能变更、从零开发项目等），必须先使用\`openspec-explore\`技能确认需求，再根据实际情况，使用\`openspec\`的其它技能。
 - 每个经确认的变更完成并通过全部测试与验证后，必须创建一个对应的 Git commit，以支持追踪和回滚；不得提交未完成或验证失败的状态。
 - 每个变更都必须依据对应 OpenSpec 的需求、场景和任务编写或更新相关测试；交付前必须解决所有测试与验证失败，不得跳过或隐瞒失败。
-- 所有项目管理的日志必须直接写入项目根目录 \`logs/\`，不得通过环境变量改写目录或创建服务、实例、日期等日志子目录。
-- 生产部署必须使用 \`wdyy-deployment-standard\`：在 Linux、macOS Docker Desktop 或 Windows Docker Desktop + WSL2/Linux 容器模式中，只使用已有基础镜像构建前后端两个独立 Linux 镜像，分别导出后封装为一个压缩包；数据库直连远程实例且不得使用数据库容器；解压后无参数执行 \`./deploy.sh\`，一次性部署整个前后端项目栈。禁止原生 PowerShell、Windows 容器模式、自动拉取镜像、交互菜单和单独操作一个服务。
-- 不得静默吞错、跳过验证、以兜底逻辑掩盖未决问题。
+- 日志实现必须使用 \`wdyy-logging-standard\`，并保持日志直接写入项目根目录 \`logs/\` 的项目边界。
+- 生产交付必须使用 \`wdyy-deployment-standard\`，并保持前后端双镜像、远程数据库和整栈一键部署的项目边界。
+- 不得静默吞错、跳过验证或以兜底逻辑掩盖未决问题。
 `;
 
 const bugRecordTemplate = '- 日期：yyyy-mm-dd\n- 问题描述：\n- 解决方法：\n';
 
 function printHelp() {
   console.log('用法: wdyy init');
-  console.log('在当前项目生成 AGENTS 规则、安装 wdyy Skill，并执行 openspec init。');
+  console.log('请先按提示手工安装外部依赖；命令将在当前项目生成 AGENTS 规则、安装 wdyy Skill，并执行 openspec init --tools agents 与 codegraph init。');
+  console.log('用法: wdyy validate');
+  console.log('只读验证当前项目的初始化产物、工具链和 Skill 完整性。');
   console.log('用法: wdyy update-skill <skill-name> | --all');
-  console.log('仅更新当前项目的一个或全部受管理 wdyy Skill，不执行项目初始化。');
+  console.log('仅更新系统用户目录中的一个或全部受管理 wdyy Skill，不执行项目初始化。');
+}
+
+function printManualPrerequisites() {
+  console.log('请先手工执行以下安装命令：');
+  for (const command of manualPrerequisiteCommands) console.log(command);
+}
+
+function inspectCommand(command, displayName) {
+  const result = spawnSync(command, ['--version'], { encoding: 'utf8', timeout: 10_000 });
+  if (result.error || result.status !== 0) {
+    const detail = result.error?.message ?? `退出码 ${result.status ?? 1}`;
+    return { problem: `${displayName} 命令不可用: ${detail}` };
+  }
+  const version = `${result.stdout ?? ''}`.split(/\r?\n/).find((line) => line.trim())?.trim();
+  if (!version) return { problem: `${displayName} 未返回版本信息` };
+  return { version };
+}
+
+async function inspectPrerequisites(skillsRoot = getGlobalSkillsRoot()) {
+  const problems = [];
+  const tools = { node: process.version };
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  if (!Number.isInteger(requiredNodeMajor) || nodeMajor < requiredNodeMajor) {
+    problems.push(`Node.js 版本不符合要求: 当前 ${process.version}，要求 >=${requiredNodeMajor}`);
+  }
+  for (const [command, displayName] of [['pnpm', 'pnpm'], ['git', 'Git'], ['openspec', 'OpenSpec'], ['codegraph', 'CodeGraph']]) {
+    const inspection = inspectCommand(command, displayName);
+    if (inspection.problem) problems.push(inspection.problem);
+    else tools[command] = inspection.version;
+  }
+  if (tools.pnpm !== requiredPnpmVersion) {
+    problems.push(`pnpm 版本不符合要求: 当前 ${tools.pnpm ?? '不可用'}，要求 ${requiredPnpmVersion}`);
+  }
+  for (const skillName of requiredPublicSkillNames) {
+    try {
+      await access(join(skillsRoot, skillName, 'SKILL.md'));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      problems.push(`缺少公共 Skill: ${skillName}`);
+    }
+  }
+  return { problems, tools };
+}
+
+function reportProblems(problems) {
+  for (const problem of problems) console.error(`- ${problem}`);
+}
+
+async function hashFile(path) {
+  return createHash('sha256').update(await readFile(path)).digest('hex');
+}
+
+async function createToolchainManifest(targetRoot, agentsFile, tools, skillsRoot = getGlobalSkillsRoot()) {
+  const publicSkills = {};
+  for (const name of requiredPublicSkillNames) publicSkills[name] = await hashFile(join(skillsRoot, name, 'SKILL.md'));
+  const managedSkills = {};
+  for (const name of managedSkillNames) managedSkills[name] = await hashFile(join(skillsRoot, name, 'SKILL.md'));
+  return {
+    initializer: { name: packageMetadata.name, version: packageMetadata.version },
+    tools,
+    agentsFile,
+    skills: { public: publicSkills, managed: managedSkills }
+  };
+}
+
+async function writeToolchainManifest(targetRoot, agentsFile, tools, writtenPaths) {
+  const toolchainRoot = join(targetRoot, '.wdyy');
+  const manifestPath = join(toolchainRoot, 'toolchain.json');
+  await mkdir(toolchainRoot, { recursive: true });
+  const manifest = await createToolchainManifest(targetRoot, agentsFile, tools);
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  writtenPaths.push(manifestPath);
+  console.log(`已写入工具链清单: ${manifestPath}`);
 }
 
 async function installManagedSkills(skillsRoot, writtenPaths, skillNames = managedSkillNames) {
@@ -231,28 +344,27 @@ async function writeAgentsFile(targetRoot, writtenPaths) {
   await writeFile(destination, generatedAgentsContent, 'utf8');
   writtenPaths.push(destination);
   console.log(`已写入项目规则: ${destination}`);
+  return basename(destination);
 }
 
-async function appendBugRecordTemplate(targetRoot, writtenPaths) {
+async function createBugRecordTemplate(targetRoot, writtenPaths) {
   const docsRoot = join(targetRoot, 'docs');
   const bugRecordPath = join(docsRoot, 'bug_record.md');
   await mkdir(docsRoot, { recursive: true });
-
-  let prefix = '';
   try {
-    const existing = await readFile(bugRecordPath, 'utf8');
-    if (existing.length > 0) prefix = existing.endsWith('\n') ? '\n' : '\n\n';
+    await access(bugRecordPath);
+    console.log(`已保留 BUG 记录: ${bugRecordPath}`);
+    return;
   } catch (error) {
     if (error.code !== 'ENOENT') throw error;
   }
-
-  await appendFile(bugRecordPath, `${prefix}${bugRecordTemplate}`, 'utf8');
+  await writeFile(bugRecordPath, bugRecordTemplate, 'utf8');
   writtenPaths.push(bugRecordPath);
-  console.log(`已更新 BUG 记录模板: ${bugRecordPath}`);
+  console.log(`已创建 BUG 记录模板: ${bugRecordPath}`);
 }
 
 function initializeOpenSpec(targetRoot, writtenPaths) {
-  const result = spawnSync('openspec', ['init'], { cwd: targetRoot, stdio: 'inherit' });
+  const result = spawnSync('openspec', ['init', '--tools', 'agents'], { cwd: targetRoot, stdio: 'inherit' });
   if (result.error || result.status !== 0) {
     const detail = result.error?.message ?? `退出码 ${result.status ?? 1}`;
     console.error(`OpenSpec 初始化失败: ${detail}`);
@@ -264,21 +376,105 @@ function initializeOpenSpec(targetRoot, writtenPaths) {
   return 0;
 }
 
+function initializeCodeGraph(targetRoot, writtenPaths) {
+  const result = spawnSync('codegraph', ['init'], { cwd: targetRoot, stdio: 'inherit' });
+  if (result.error || result.status !== 0) {
+    const detail = result.error?.message ?? `退出码 ${result.status ?? 1}`;
+    console.error(`CodeGraph 初始化失败: ${detail}`);
+    printWrittenPaths(writtenPaths);
+    return result.status ?? 1;
+  }
+
+  console.log('CodeGraph 初始化完成。');
+  return 0;
+}
+
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function validateProject(targetRoot) {
+  const problems = [];
+  const skillsRoot = getGlobalSkillsRoot();
+  const prerequisites = await inspectPrerequisites(skillsRoot);
+  problems.push(...prerequisites.problems);
+
+  for (const path of ['.git', ...defaultProjectDirectories, '.env.example', 'docs/bug_record.md', 'openspec', '.codegraph']) {
+    if (!await pathExists(join(targetRoot, path))) problems.push(`缺少初始化产物: ${path}`);
+  }
+
+  const gitIgnorePath = join(targetRoot, '.gitignore');
+  if (!await pathExists(gitIgnorePath)) {
+    problems.push('缺少初始化产物: .gitignore');
+  } else {
+    const entries = new Set((await readFile(gitIgnorePath, 'utf8')).split(/\r?\n/).map((entry) => entry.trim()).filter(Boolean));
+    for (const entry of requiredGitIgnoreEntries) if (!entries.has(entry)) problems.push(`.gitignore 缺少规则: ${entry}`);
+  }
+
+  const manifestPath = join(targetRoot, '.wdyy', 'toolchain.json');
+  if (!await pathExists(manifestPath)) {
+    problems.push('缺少初始化产物: .wdyy/toolchain.json');
+  } else {
+    try {
+      const actualText = await readFile(manifestPath, 'utf8');
+      const actual = JSON.parse(actualText);
+      const agentsFile = actual.agentsFile;
+      if (!['AGENTS.md', 'AGENTS_new.md'].includes(agentsFile)) {
+        problems.push('工具链清单中的规则文件路径无效');
+      } else if (!await pathExists(join(targetRoot, agentsFile))) {
+        problems.push(`缺少工具链清单声明的规则文件: ${agentsFile}`);
+      } else if (await readFile(join(targetRoot, agentsFile), 'utf8') !== generatedAgentsContent) {
+        problems.push(`项目规则已漂移: ${agentsFile}`);
+      }
+      if (prerequisites.problems.length === 0 && ['AGENTS.md', 'AGENTS_new.md'].includes(agentsFile)) {
+        const expected = `${JSON.stringify(await createToolchainManifest(targetRoot, agentsFile, prerequisites.tools, skillsRoot), null, 2)}\n`;
+        if (actualText !== expected) problems.push('工具链清单与当前工具或 Skill 不一致');
+      }
+    } catch (error) {
+      problems.push(`工具链清单不可读: ${error.message}`);
+    }
+  }
+
+  if (problems.length > 0) {
+    console.error('wdyy 验证失败:');
+    reportProblems(problems);
+    return 1;
+  }
+  console.log('wdyy 验证通过。');
+  return 0;
+}
+
 export async function run(argumentsList) {
   if (argumentsList.length === 1 && argumentsList[0] === 'init') {
     const writtenPaths = [];
     try {
+      printManualPrerequisites();
+      const prerequisites = await inspectPrerequisites();
+      if (prerequisites.problems.length > 0) {
+        console.error('初始化前置条件不满足:');
+        reportProblems(prerequisites.problems);
+        return 1;
+      }
       const gitExitCode = initializeGit(process.cwd(), writtenPaths);
       if (gitExitCode !== 0) return gitExitCode;
-      await writeAgentsFile(process.cwd(), writtenPaths);
+      const agentsFile = await writeAgentsFile(process.cwd(), writtenPaths);
       const globalSkillsRoot = getGlobalSkillsRoot();
       await installManagedSkills(globalSkillsRoot, writtenPaths);
       await removeDeprecatedManagedSkills(globalSkillsRoot, writtenPaths);
       await appendGitIgnoreEntries(process.cwd(), writtenPaths);
       await createDefaultProjectLayout(process.cwd(), writtenPaths);
-      await appendBugRecordTemplate(process.cwd(), writtenPaths);
+      await createBugRecordTemplate(process.cwd(), writtenPaths);
       const openSpecExitCode = initializeOpenSpec(process.cwd(), writtenPaths);
       if (openSpecExitCode !== 0) return openSpecExitCode;
+      const codeGraphExitCode = initializeCodeGraph(process.cwd(), writtenPaths);
+      if (codeGraphExitCode !== 0) return codeGraphExitCode;
+      await writeToolchainManifest(process.cwd(), agentsFile, prerequisites.tools, writtenPaths);
       console.log('wdyy 初始化完成。');
       return 0;
     } catch (error) {
@@ -288,6 +484,15 @@ export async function run(argumentsList) {
     }
   }
 
+  if (argumentsList.length === 1 && argumentsList[0] === 'validate') {
+    try {
+      return await validateProject(process.cwd());
+    } catch (error) {
+      console.error(`wdyy 验证失败: ${error.message}`);
+      return 1;
+    }
+  }
+
   if (argumentsList[0] === 'update-skill') {
     const skillArguments = argumentsList.slice(1);
     const updateAll = skillArguments.length === 1 && skillArguments[0] === '--all';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdyy/skills",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "企业内部开发 Skill 与项目初始化命令",
   "type": "module",
   "packageManager": "pnpm@12.1.0",