{"id":"9f681cc9-c0cb-46b6-8a42-cb8702f9f79d","entityType":"agent","slug":"clawhub-ai-acheng-harness-dev-standards","name":"Harness Dev Standards","canonicalUrl":"https://www.xpersona.co/agent/clawhub-ai-acheng-harness-dev-standards","canonicalPath":"/agent/clawhub-ai-acheng-harness-dev-standards","generatedAt":"2026-10-11T11:24:02.221Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T08:54:10.753Z","emptyReason":null},"description":"Provides a full-cycle, automated quality gate and governance framework to ensure standardized, error-free code delivery in Harness Engineering projects. Skill: Harness Dev Standards Owner: ai-acheng Summary: Provides a full-cycle, automated quality gate and governance framework to ensure standardized, error-free code delivery in Harness Engineering projects. Tags: latest:1.0.3 Version history: v1.0.3 | 2026-08-17T08:56:38.446Z | auto - Added new directories/files: marketing, references, and scripts to enhance documentation and automation. - Removed skill-card.md to s","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17e1hdx8tza0g6m8aaym7p9ex84vv0m:harness-dev-standards","sourceUrl":"https://clawhub.ai/ai-acheng/harness-dev-standards","homepage":"https://clawhub.ai/ai-acheng/skills/harness-dev-standards","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/ai-acheng/harness-dev-standards","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/ai-acheng/skills/harness-dev-standards","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Provides a full-cycle, automated quality gate and governance framework to ensure standardized, error-free code delivery in Harness Engineering projects. Skill: "},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:54:10.753Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:54:10.753Z","emptyReason":null},"stars":null,"forks":null,"downloads":1107,"packageName":null,"latestVersion":"1.0.3","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:54:10.674Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T08:54:10.753Z","lastCrawledAt":"2026-10-11T08:54:10.674Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T08:54:10.675Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.3","createdAt":"2026-08-17T08:56:38.446Z","changelog":"- Added new directories/files: marketing, references, and scripts to enhance documentation and automation. - Removed skill-card.md to streamline project documentation. - Expanded reference content for standards, checklists, and auto-remediation. - Improved project structure and tools organization for better maintainability.","fileCount":15,"zipByteSize":28342},{"version":"1.0.2","createdAt":"2026-05-13T12:13:43.936Z","changelog":"- Updated marketing materials in 00-intro-short.md, 01-vs-superpowers.md, and 02-vs-qcsd-quality-gates.md for improved clarity and positioning. - Made minor refinements to skill.json. - No changes to main development standards or workflow descriptions.","fileCount":12,"zipByteSize":28087},{"version":"1.0.1","createdAt":"2026-05-13T11:58:57.330Z","changelog":"- 更新了开发规范体系的描述，将“基于腾讯全AI研发实践改进”调整为“基于企业级全AI研发实践改进” - 规范文档相关表述从“腾讯全AI研发实践”升级为“企业级全AI研发实践” - 未涉及核心标准及质控流程变更，主体结构与内容保持一致 - 文档表述更中性，适应更广泛企业场景","fileCount":11,"zipByteSize":26793},{"version":"1.0.0","createdAt":"2026-05-13T11:54:20.623Z","changelog":"Initial release of Harness Engineering 开发规范体系. - 提供完整全流程代码交付质量保障和自动治理标准，结合腾讯全AI研发实践 - 明确六大质量门禁（需求、架构、编码、依赖、环境、交付）并给出详细检查项 - 支持项目自动治理：包括依赖、语法、类型等常见问题的自动检测与修复策略和流程 - 定义 Next.js 等前端项目标准文件结构与 README 写作要求 - 提供依赖/质量扫描等内置工具脚本 - 配套交付前检查清单和参考文档，便于项目自查和标准推广","fileCount":11,"zipByteSize":26785}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17e1hdx8tza0g6m8aaym7p9ex84vv0m:harness-dev-standards","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ai-acheng-harness-dev-standards/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ai-acheng-harness-dev-standards/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ai-acheng-harness-dev-standards/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ai-acheng-harness-dev-standards/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ai-acheng-harness-dev-standards/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-ai-acheng-harness-dev-standards/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T11:24:02.217Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ai-acheng-harness-dev-standards/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ai-acheng-harness-dev-standards/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ai-acheng-harness-dev-standards/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-ai-acheng-harness-dev-standards/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T08:54:10.753Z","emptyReason":null},"readme":"Skill: Harness Dev Standards\n\nOwner: ai-acheng\n\nSummary: Provides a full-cycle, automated quality gate and governance framework to ensure standardized, error-free code delivery in Harness Engineering projects.\n\nTags: latest:1.0.3\n\nVersion history:\n\nv1.0.3 | 2026-08-17T08:56:38.446Z | auto\n\n- Added new directories/files: marketing, references, and scripts to enhance documentation and automation.\n- Removed skill-card.md to streamline project documentation.\n- Expanded reference content for standards, checklists, and auto-remediation.\n- Improved project structure and tools organization for better maintainability.\n\nv1.0.2 | 2026-05-13T12:13:43.936Z | auto\n\n- Updated marketing materials in 00-intro-short.md, 01-vs-superpowers.md, and 02-vs-qcsd-quality-gates.md for improved clarity and positioning.\n- Made minor refinements to skill.json.\n- No changes to main development standards or workflow descriptions.\n\nv1.0.1 | 2026-05-13T11:58:57.330Z | auto\n\n- 更新了开发规范体系的描述，将“基于腾讯全AI研发实践改进”调整为“基于企业级全AI研发实践改进”\n- 规范文档相关表述从“腾讯全AI研发实践”升级为“企业级全AI研发实践”\n- 未涉及核心标准及质控流程变更，主体结构与内容保持一致\n- 文档表述更中性，适应更广泛企业场景\n\nv1.0.0 | 2026-05-13T11:54:20.623Z | auto\n\nInitial release of Harness Engineering 开发规范体系.\n\n- 提供完整全流程代码交付质量保障和自动治理标准，结合腾讯全AI研发实践\n- 明确六大质量门禁（需求、架构、编码、依赖、环境、交付）并给出详细检查项\n- 支持项目自动治理：包括依赖、语法、类型等常见问题的自动检测与修复策略和流程\n- 定义 Next.js 等前端项目标准文件结构与 README 写作要求\n- 提供依赖/质量扫描等内置工具脚本\n- 配套交付前检查清单和参考文档，便于项目自查和标准推广\n\nArchive index:\n\nArchive v1.0.3: 15 files, 28342 bytes\n\nFiles: marketing (0b), marketing/00-intro-short.md (3427b), marketing/01-vs-superpowers.md (5897b), marketing/02-vs-qcsd-quality-gates.md (7931b), references (0b), references/checklist.md (6090b), references/remediation.md (10537b), references/standards.md (9391b), scripts (0b), scripts/depcheck.sh (3417b), scripts/quality-scan.sh (3393b), skill-card.md (2241b), skill.json (653b), SKILL.md (6284b), _meta.json (140b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: harness-dev-standards\ndescription: Harness Engineering 开发规范体系 - 全流程质量门禁与自动治理标准。基于企业级全AI研发实践改进，提供完整的代码交付质量保障框架。Use when: (1) 启动新项目开发前, (2) 代码交付前做质量检查, (3) 需要标准化开发流程, (4) 执行架构评审、代码评审, (5) 排查依赖/环境问题\n---\n\n# Harness Engineering 开发规范体系\n\n## 核心哲学\n\n> **\"质量不是检查出来的，是构建出来的\"**\n\n基于 Harness Engineering 理念 + 企业级全AI研发实践，构建从需求到交付的全链路质量保障体系。\n\n---\n\n## 🚀 快速启动\n\n### 新项目初始化检查清单\n\n**每次启动新项目必须执行：**\n\n```bash\n# 1. 检查目录结构是否符合标准\n# 2. 检查 package.json 依赖完整性\n# 3. 检查 .env.example 配置完整性\n# 4. 检查 README 文档完整性\n```\n\n---\n\n## 🔐 质量门禁 (Quality Gates)\n\n**每次交付必须通过以下 6 道门禁：**\n\n### 1. 需求门禁 (Requirement Gate)\n- ✅ 需求完整清晰，无模糊点\n- ✅ 所有需求点已记录到任务追踪\n- ✅ 技术可行性已验证\n- ✅ 依赖边界已明确\n\n### 2. 架构门禁 (Architecture Gate)\n- ✅ 技术选型适合单人开发\n- ✅ 文件结构清晰，符合标准化规范\n- ✅ 依赖最小化，无冗余包\n- ✅ 扩展性设计合理\n\n**参考：** 查看 [references/standards.md](references/standards.md) 标准化文件结构\n\n### 3. 编码门禁 (Coding Gate)\n- ✅ 语法正确，无 TypeScript/JavaScript 错误\n- ✅ import 路径全部正确\n- ✅ 命名规范清晰（camelCase 变量、PascalCase 组件）\n- ✅ 不遗漏任何功能点\n- ✅ 类型定义完整，无 `any` 滥用\n\n### 4. 依赖门禁 (Dependency Gate)\n- ✅ package.json 包含所有需要的依赖\n- ✅ 无多余依赖（`depcheck` 验证）\n- ✅ 依赖版本稳定（非 alpha/beta）\n- ✅ lockfile 已提交（pnpm-lock.yaml / package-lock.json）\n\n**工具：** 运行 `scripts/depcheck.sh` 自动检查\n\n### 5. 环境门禁 (Environment Gate)\n- ✅ .env.example 包含所有需要的配置\n- ✅ 每个配置项有说明注释\n- ✅ 敏感信息不提交到 git\n- ✅ .gitignore 配置正确\n\n### 6. 交付门禁 (Delivery Gate)\n- ✅ 所有需求点都已实现\n- ✅ 项目能正常启动\n- ✅ README 写清楚使用方法\n- ✅ 构建无错误（`npm run build` 验证）\n\n---\n\n## 🤖 自动治理 (Auto Remediation)\n\n出现以下问题时，**自动修复，无需人工干预：**\n\n| 问题类型 | 自动修复策略 |\n|---------|------------|\n| 依赖安装报错 | 分析错误 → 修改版本号或移除多余依赖 |\n| import 路径错误 | 自动查找正确路径修复 |\n| 语法错误 | 自动修正 TypeScript/JavaScript 语法 |\n| 启动失败 | 读取错误日志 → 修复后重新检查 |\n| 类型错误 | 补全类型定义或修正类型不匹配 |\n\n**修复流程：**\n1. 识别错误信息\n2. 定位问题代码位置\n3. 应用修复策略\n4. 验证修复结果\n5. 重复直到问题解决\n\n---\n\n## 📁 标准化文件结构\n\n### Next.js 项目标准结构\n\n```\nproject-name/\n├── app/ # Next.js App Router\n│ ├── page.tsx # 首页\n│ ├── layout.tsx # 全局布局\n│ └── globals.css # 全局样式\n├── lib/ # 工具库、第三方客户端\n├── public/ # 静态资源\n├── .env.example # 环境变量示例\n├── .gitignore # git忽略规则\n├── package.json\n├── tsconfig.json\n├── README.md # 必须写清楚\n└── *-init.sql # 数据库初始化SQL\n```\n\n**README 必须包含：**\n- 项目介绍\n- 配置步骤\n- 启动命令\n- 环境变量说明\n\n**详细规范：** 查看 [references/standards.md](references/standards.md)\n\n---\n\n## ✅ 代码质量标准\n\n### TypeScript 规范\n\n- ✅ 类型正确，无隐式 `any`\n- ✅ 命名清晰，变量名表达用途\n- ✅ 注释够用，不冗余\n- ✅ 函数单一职责\n- ✅ 避免深层嵌套（超过 3 层考虑重构）\n\n### 项目规范\n\n- ✅ README 完整，新人能按文档启动\n- ✅ 环境配置说明清晰\n- ✅ 依赖干净，无未使用包\n- ✅ gitignore 正确，不提交敏感文件\n\n---\n\n## 🛠️ 内置工具脚本\n\n### 依赖检查脚本\n```bash\n# 运行依赖检查\n./scripts/depcheck.sh\n```\n\n功能：\n- 检测未使用的依赖\n- 检测缺失的依赖\n- 检测版本冲突\n- 生成修复建议\n\n### 代码质量扫描脚本\n```bash\n# 运行代码质量扫描\n./scripts/quality-scan.sh\n```\n\n功能：\n- TypeScript 类型检查\n- ESLint 规则检查\n- 命名规范检查\n- import 路径验证\n\n---\n\n## 📋 交付前检查清单\n\n**交付前逐项确认：**\n\n- [ ] 需求门禁：所有需求点实现完毕\n- [ ] 架构门禁：文件结构符合标准\n- [ ] 编码门禁：无语法/类型错误\n- [ ] 依赖门禁：依赖干净无冗余\n- [ ] 环境门禁：.env.example 完整\n- [ ] 交付门禁：项目能正常启动构建\n- [ ] README：包含完整使用说明\n\n---\n\n## 📚 参考文档\n\n| 文档 | 内容 |\n|-----|------|\n| [references/standards.md](references/standards.md) | 详细文件结构规范 + 命名规范 |\n| [references/checklist.md](references/checklist.md) | 完整交付检查清单模板 |\n| [references/remediation.md](references/remediation.md) | 常见问题自动修复策略库 |\n\n---\n\n## 💡 设计理念\n\n### 为什么这样设计？\n\n1. **前置质量** - 把质量检查左移到开发过程每个环节，不是最后才检查\n2. **自动修复** - 能自动修的绝不麻烦人，解放生产力\n3. **标准化** - 降低认知负担，所有项目看起来都一样\n4. **渐进式** - 不追求完美，每次交付比上一次更好\n\n### 和传统开发流程的区别\n\n| 传统流程 | Harness Engineering |\n|---------|-------------------|\n| 最后统一测试 | 每一步都有质量门禁 |\n| 人找问题 | 问题自动暴露并修复 |\n| 每个项目结构都不一样 | 标准化结构，上手成本为0 |\n| 依赖问题靠经验解决 | 自动检测并给出修复方案 |\n\n---\n\n*\"The best code is the code you don't have to think about.\"* - Harness Engineering Philosophy\n\nFile v1.0.3:_meta.json\n\n{\n \"ownerId\": \"kn7ffzw77tj6c8yw14p92w963984vgsq\",\n \"slug\": \"harness-dev-standards\",\n \"version\": \"1.0.3\",\n \"publishedAt\": 1786956998446\n}\n\nFile v1.0.3:references/checklist.md\n\n# 完整交付检查清单\n\n## 目录\n\n- [项目交付前检查清单](#项目交付前检查清单)\n- [代码评审检查清单](#代码评审检查清单)\n- [发布前检查清单](#发布前检查清单)\n- [安全检查清单](#安全检查清单)\n\n---\n\n## 项目交付前检查清单\n\n### 📋 需求检查\n\n- [ ] 所有需求点已实现\n- [ ] 需求变更已记录\n- [ ] 边缘情况已处理\n- [ ] 用户验收标准已满足\n\n### 🏗️ 架构检查\n\n- [ ] 文件结构符合标准化规范\n- [ ] 无冗余目录或文件\n- [ ] 依赖关系清晰\n- [ ] 模块划分合理\n\n### 💻 代码质量检查\n\n- [ ] TypeScript 类型检查通过 (`tsc --noEmit`)\n- [ ] ESLint 检查通过无错误\n- [ ] 无未使用的变量或导入\n- [ ] 无 `any` 类型滥用\n- [ ] 命名清晰符合规范\n- [ ] 注释充分且有意义\n- [ ] 无重复代码块\n- [ ] 函数单一职责（不超过 50 行）\n- [ ] 嵌套层级不超过 3 层\n\n### 📦 依赖检查\n\n- [ ] package.json 包含所有依赖\n- [ ] 无未使用的依赖 (`depcheck` 验证)\n- [ ] 依赖版本稳定（非 alpha/beta/rc）\n- [ ] lockfile 已提交\n- [ ] 无已知安全漏洞 (`npm audit` 验证)\n\n### 🌍 环境检查\n\n- [ ] .env.example 包含所有配置项\n- [ ] 每个配置项有说明注释\n- [ ] .env.local 已加入 .gitignore\n- [ ] 敏感信息未提交到 git\n- [ ] .gitignore 配置正确\n\n### 📖 文档检查\n\n- [ ] README.md 完整\n- [ ] README 包含项目介绍\n- [ ] README 包含快速开始指南\n- [ ] README 包含环境变量说明\n- [ ] README 包含部署说明\n- [ ] 代码注释清晰易懂\n- [ ] API 文档（如有）已更新\n\n### ✅ 功能验证\n\n- [ ] 项目能正常启动\n- [ ] 项目能正常构建 (`npm run build`)\n- [ ] 主要功能流程可正常执行\n- [ ] 错误边界已处理\n- [ ] 加载状态有反馈\n\n---\n\n## 代码评审检查清单\n\n### 代码正确性\n\n- [ ] 逻辑正确，无明显 bug\n- [ ] 边界条件已处理\n- [ ] 错误处理完善\n- [ ] 异步操作正确处理\n- [ ] 并发问题已考虑\n\n### 代码质量\n\n- [ ] 代码简洁，无冗余\n- [ ] 命名清晰，表达准确\n- [ ] 函数/类职责单一\n- [ ] 无重复代码\n- [ ] 无魔法数字/字符串\n\n### 性能考虑\n\n- [ ] 无不必要的重渲染\n- [ ] 大数据量场景已优化\n- [ ] 内存泄漏风险已检查\n- [ ] 网络请求有缓存策略\n\n### 安全性\n\n- [ ] XSS 风险已处理\n- [ ] SQL 注入风险已处理\n- [ ] 用户输入已验证\n- [ ] 敏感信息未日志输出\n- [ ] 认证授权逻辑正确\n\n### 可维护性\n\n- [ ] 代码结构清晰\n- [ ] 注释充分\n- [ ] 符合团队规范\n- [ ] 测试用例充分\n\n---\n\n## 发布前检查清单\n\n### 构建检查\n\n- [ ] 生产构建无错误\n- [ ] 构建产物大小合理\n- [ ] Tree shaking 生效\n- [ ] 无用代码已移除\n\n### 配置检查\n\n- [ ] 生产环境配置正确\n- [ ] API 端点指向生产\n- [ ] Debug 模式已关闭\n- [ ] Log 级别配置正确\n\n### 功能检查\n\n- [ ] 冒烟测试通过\n- [ ] 核心功能验证通过\n- [ ] 回归测试通过\n- [ ] 性能指标达标\n\n### 监控检查\n\n- [ ] 错误监控已配置\n- [ ] 性能监控已配置\n- [ ] 日志收集已配置\n- [ ] 告警规则已设置\n\n### 回滚准备\n\n- [ ] 上一版本备份存在\n- [ ] 回滚流程已明确\n- [ ] 数据库迁移可回滚\n- [ ] 配置回滚方案已准备\n\n---\n\n## 安全检查清单\n\n### 认证与授权\n\n- [ ] JWT secret 足够复杂\n- [ ] Token 过期时间合理\n- [ ] 权限边界清晰\n- [ ] 越权访问已防护\n- [ ] 登录失败有锁定机制\n\n### 输入验证\n\n- [ ] 所有用户输入已验证\n- [ ] 验证在服务端执行\n- [ ] 输入长度有限制\n- [ ] 特殊字符已处理\n- [ ] 文件上传有类型/大小限制\n\n### 输出编码\n\n- [ ] XSS 防护已启用\n- [ ] HTML 输出已编码\n- [ ] JSON 输出正确\n- [ ] 响应头安全配置\n\n### 数据保护\n\n- [ ] 密码已加密存储（bcrypt/argon2）\n- [ ] 敏感数据传输使用 HTTPS\n- [ ] 数据库连接信息加密\n- [ ] 日志不含敏感信息\n- [ ] PII 数据有保护措施\n\n### 依赖安全\n\n- [ ] 定期运行 `npm audit`\n- [ ] 高危漏洞已修复\n- [ ] 不使用已废弃的包\n- [ ] 依赖来源可信\n- [ ] 有依赖更新机制\n\n---\n\n## 自动检查脚本使用说明\n\n### 运行全部检查\n\n```bash\n# 进入项目目录\ncd your-project\n\n# 运行质量扫描\nbash scripts/quality-scan.sh\n```\n\n### 单独运行检查\n\n```bash\n# TypeScript 类型检查\nnpx tsc --noEmit\n\n# ESLint 检查\nnpx eslint . --ext .ts,.tsx\n\n# 依赖检查\nnpx depcheck\n\n# 安全漏洞检查\nnpm audit\n\n# 构建检查\nnpm run build\n```\n\n### 检查结果判定\n\n| 检查项 | 通过标准 |\n|--------|---------|\n| TypeScript | 0 errors |\n| ESLint | 0 errors, warnings 可接受但尽量少 |\n| depcheck | 0 unused dependencies |\n| npm audit | 0 critical, 0 high |\n| build | 成功完成无错误 |\n\n---\n\n## 常见问题排查\n\n### 依赖安装失败\n\n1. 检查 Node.js 版本是否符合要求\n2. 删除 lockfile 和 node_modules 重新安装\n3. 检查网络连接和 npm 源配置\n4. 尝试降级有问题的依赖版本\n\n### 类型检查失败\n\n1. 检查类型定义是否完整\n2. 检查 import 路径是否正确\n3. 检查 tsconfig.json 配置\n4. 必要时使用 `// @ts-ignore` 但要加注释说明\n\n### 构建失败\n\n1. 检查环境变量是否配置完整\n2. 检查是否有未使用的导入\n3. 检查路径别名配置是否正确\n4. 查看详细错误日志定位问题\n\n---\n\n## 检查清单使用指南\n\n### 如何高效使用\n\n1. **提前使用** - 不要等到交付前才检查，开发过程中逐项确认\n2. **自动化优先** - 能自动化的检查项全部做成脚本自动运行\n3. **结对验证** - 重要项目让另一个人过一遍清单\n4. **持续改进** - 根据实际情况更新清单内容\n\n### 不同项目的裁剪\n\n- **小型工具项目** - 可跳过部分架构和性能检查\n- **核心业务项目** - 必须通过全部检查项\n- **开源项目** - 额外增加文档和示例代码检查\n- **安全敏感项目** - 重点关注安全检查清单\n\n---\n\n*本清单基于 Harness Engineering 质量门禁理念制定*\n\nFile v1.0.3:references/remediation.md\n\n# 常见问题自动修复策略库\n\n## 目录\n\n- [依赖问题修复](#依赖问题修复)\n- [TypeScript 类型错误修复](#typescript-类型错误修复)\n- [Import 路径错误修复](#import-路径错误修复)\n- [语法错误修复](#语法错误修复)\n- [启动失败修复](#启动失败修复)\n- [构建错误修复](#构建错误修复)\n\n---\n\n## 依赖问题修复\n\n### 问题 1: 依赖版本冲突\n\n**错误信息：**\n```\nnpm ERR! code ERESOLVE\nnpm ERR! ERESOLVE could not resolve dependency\n```\n\n**自动修复策略：**\n\n1. **识别冲突包** - 从错误信息中提取冲突的包名和版本范围\n2. **查看 peerDependencies** - 检查冲突包的对等依赖要求\n3. **应用以下修复方案：**\n\n **方案 A: 使用 --legacy-peer-deps（临时方案）**\n ```bash\n npm install --legacy-peer-deps\n # 或\n pnpm install --no-strict-peer-dependencies\n ```\n\n **方案 B: 升级/降级冲突包**\n - 查找兼容的版本组合\n - 更新 package.json 中的版本号\n - 重新安装\n\n **方案 C: 使用 overrides（npm）或 resolutions（pnpm）**\n ```json\n // package.json\n {\n \"overrides\": {\n \"react\": \"^18.0.0\"\n }\n }\n ```\n\n4. **验证修复** - 重新运行 install 确认问题解决\n\n---\n\n### 问题 2: 未使用的依赖\n\n**错误信息：**\n```\nUnused dependencies found:\n- package-a\n- package-b\n```\n\n**自动修复策略：**\n\n1. **二次确认** - 检查代码中是否真的没有使用这些包\n - 搜索 import 语句\n - 搜索 require 调用\n - 检查配置文件中的引用\n\n2. **安全移除** - 如果确认未使用：\n ```bash\n npm uninstall package-a package-b\n # 或\n pnpm remove package-a package-b\n ```\n\n3. **注意事项**\n - 不要移除仅在配置文件中引用的包\n - 不要移除 peerDependencies 中声明的包\n - 某些包可能通过字符串动态导入，需要特殊处理\n\n---\n\n### 问题 3: 缺失的依赖\n\n**错误信息：**\n```\nCannot find module 'missing-package'\n```\n\n**自动修复策略：**\n\n1. **识别缺失包名** - 从错误信息提取\n2. **检查是否为 devDependency** - 有些包可能只在开发环境需要\n3. **安装依赖**：\n ```bash\n npm install missing-package\n # 或开发依赖\n npm install -D missing-package\n ```\n\n4. **特殊情况处理**\n - 如果是类型定义缺失：`npm install -D @types/missing-package`\n - 如果是 monorepo 内部包：检查 workspace 配置\n - 如果是私有包：检查 npm registry 配置\n\n---\n\n### 问题 4: 安全漏洞\n\n**错误信息：**\n```\nnpm audit found 3 high severity vulnerabilities\n```\n\n**自动修复策略：**\n\n1. **运行自动修复**：\n ```bash\n npm audit fix\n ```\n\n2. 如果自动修复无法解决：\n - 查看漏洞详情：`npm audit`\n - 检查受影响包的最新版本是否修复\n - 如果有修复版本，手动升级：`npm update vulnerable-package`\n - 如果无法升级，考虑使用替代包或添加忽略说明\n\n3. **记录说明** - 如果必须保留有漏洞的版本，在代码中添加注释说明原因\n\n---\n\n## TypeScript 类型错误修复\n\n### 问题 1: 隐式 any 类型\n\n**错误信息：**\n```\nParameter 'x' implicitly has an 'any' type.\n```\n\n**自动修复策略：**\n\n1. **推断类型** - 根据参数使用方式推断合理的类型\n2. **添加类型注解**：\n ```typescript\n // 修复前\n function process(x) { ... }\n \n // 修复后\n function process(x: string) { ... }\n ```\n\n3. **如果类型确实不确定**：\n - 使用 `unknown` 而不是 `any`\n - 添加类型守卫\n ```typescript\n function process(x: unknown) {\n if (typeof x === 'string') {\n // x 在这里是 string 类型\n }\n }\n ```\n\n---\n\n### 问题 2: 类型不匹配\n\n**错误信息：**\n```\nType 'string' is not assignable to type 'number'.\n```\n\n**自动修复策略：**\n\n1. **分析上下文** - 确定期望的类型和实际的类型\n2. **应用类型转换**：\n ```typescript\n // 修复前\n const count: number = params.count;\n \n // 修复后\n const count: number = Number(params.count);\n ```\n\n3. **常见转换模式**：\n - 字符串转数字：`Number(x)` 或 `parseInt(x, 10)`\n - 任意转布尔：`Boolean(x)` 或 `!!x`\n - 联合类型收窄：使用类型守卫\n\n---\n\n### 问题 3: 可能为 null/undefined\n\n**错误信息：**\n```\nObject is possibly 'null'.\nObject is possibly 'undefined'.\n```\n\n**自动修复策略：**\n\n1. **添加空值检查**（推荐）：\n ```typescript\n // 修复前\n const name = user.name;\n \n // 修复后\n const name = user?.name;\n ```\n\n2. **如果确定不会为空**，使用非空断言：\n ```typescript\n const name = user!.name;\n ```\n\n3. **提供默认值**：\n ```typescript\n const name = user?.name ?? 'default';\n ```\n\n---\n\n### 问题 4: 缺少属性定义\n\n**错误信息：**\n```\nProperty 'email' does not exist on type 'User'.\n```\n\n**自动修复策略：**\n\n1. **找到类型定义位置**\n2. **添加缺失的属性**：\n ```typescript\n // 修复前\n interface User {\n id: number;\n name: string;\n }\n \n // 修复后\n interface User {\n id: number;\n name: string;\n email: string;\n }\n ```\n\n3. **如果是外部类型**，使用类型扩展：\n ```typescript\n declare module 'external-lib' {\n interface User {\n email: string;\n }\n }\n ```\n\n---\n\n## Import 路径错误修复\n\n### 问题 1: 模块未找到\n\n**错误信息：**\n```\nCannot find module '@/components/Button' or its corresponding type declarations.\n```\n\n**自动修复策略：**\n\n1. **检查路径别名配置** - 查看 tsconfig.json 中的 paths 配置\n2. **验证文件是否存在** - 检查目标文件的实际位置\n3. **修正路径**：\n\n **相对路径问题**：\n ```typescript\n // 修复前\n import Button from '../../components/Button';\n \n // 修复后（层数不对）\n import Button from '../../../components/Button';\n ```\n\n **路径别名问题**：\n - 确认 tsconfig.json 配置正确\n - 确认构建工具（webpack/vite）也配置了别名\n - 如果使用 Next.js，检查是否配置了 baseUrl\n\n4. **扩展名问题** - 某些环境需要明确加 `.ts` / `.tsx` 扩展名\n\n---\n\n### 问题 2: 命名导出不存在\n\n**错误信息：**\n```\nModule '\"../utils\"' has no exported member 'formatDate'.\n```\n\n**自动修复策略：**\n\n1. **检查目标模块的导出**\n2. **修正导入名称** - 可能是拼写错误\n3. **如果是默认导出**，改为默认导入：\n ```typescript\n // 修复前\n import { formatDate } from '../utils';\n \n // 修复后\n import formatDate from '../utils';\n ```\n\n4. **如果确实需要命名导出**，在目标模块添加导出：\n ```typescript\n // 在 ../utils 中添加\n export { formatDate };\n ```\n\n---\n\n## 语法错误修复\n\n### 常见 JavaScript/TypeScript 语法错误\n\n| 错误模式 | 修复方案 |\n|---------|---------|\n| 缺少分号 | 添加分号（或配置无分号风格） |\n| 括号不匹配 | 找出缺失的括号并补全 |\n| 引号不匹配 | 统一引号类型（单/双/模板字符串） |\n| `const` 变量重新赋值 | 改为 `let` 或避免重新赋值 |\n| 解构时使用保留字 | 重命名变量：`{ default: defaultVal }` |\n| 异步函数中没有 await | 添加 await 或移除 async |\n\n### 示例修复\n\n**问题：缺少闭括号**\n```typescript\n// 修复前\nfunction add(a, b {\n return a + b;\n}\n\n// 修复后\nfunction add(a, b) {\n return a + b;\n}\n```\n\n**问题：const 重新赋值**\n```typescript\n// 修复前\nconst count = 0;\ncount = 1;\n\n// 修复后\nlet count = 0;\ncount = 1;\n```\n\n---\n\n## 启动失败修复\n\n### 问题 1: 端口被占用\n\n**错误信息：**\n```\nPort 3000 is already in use.\n```\n\n**自动修复策略：**\n\n1. **查找占用进程**：\n ```bash\n lsof -i :3000\n # 或\n netstat -ano | findstr :3000\n ```\n\n2. **杀掉进程**：\n ```bash\n kill -9 \n ```\n\n3. **或使用其他端口**：\n - 修改 package.json 中的启动命令\n - 或设置环境变量 `PORT=3001`\n\n---\n\n### 问题 2: 环境变量缺失\n\n**错误信息：**\n```\nError: DATABASE_URL is not defined\n```\n\n**自动修复策略：**\n\n1. **检查 .env 文件是否存在**\n2. **检查 .env.example 中的配置项**\n3. **创建/更新 .env 文件**，添加缺失的环境变量\n4. **确认环境变量加载工具已正确配置**（dotenv 等）\n\n---\n\n### 问题 3: Node.js 版本不兼容\n\n**错误信息：**\n```\nError: Cannot find module 'node:fs'\n```\n\n**自动修复策略：**\n\n1. **检查 package.json 中的 engines 配置**\n2. **建议升级 Node.js 版本**\n3. **或降级相关依赖包到兼容版本**\n\n---\n\n## 构建错误修复\n\n### 问题 1: Next.js 构建时页面报错\n\n**错误信息：**\n```\nError occurred prerendering page \"/xxx\".\n```\n\n**自动修复策略：**\n\n1. **检查是否有服务端不支持的 API**（window, document 等）\n2. **添加动态导入或客户端标记**：\n ```typescript\n 'use client'; // 客户端组件\n \n // 或动态导入\n const Component = dynamic(() => import('./Component'), {\n ssr: false\n });\n ```\n\n3. **检查 getStaticProps/getServerSideProps 中的错误**\n4. **检查数据获取是否有异常未捕获**\n\n---\n\n### 问题 2: 构建产物过大\n\n**警告信息：**\n```\nWarning: asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).\n```\n\n**自动修复策略：**\n\n1. **分析 bundle 组成**：\n ```bash\n npx webpack-bundle-analyzer\n # 或 Next.js 内置分析\n ANALYZE=true npm run build\n ```\n\n2. **应用优化手段**：\n - 代码分割（动态 import）\n - 移除未使用的依赖\n - 使用更轻量的替代库\n - 启用 Tree Shaking\n - 配置 externals\n\n---\n\n## 修复验证流程\n\n每次自动修复后，必须执行以下验证：\n\n1. **重新运行出错的命令** - 确认错误已解决\n2. **运行类型检查** - `npx tsc --noEmit`\n3. **运行 lint 检查** - `npx eslint .`\n4. **尝试启动项目** - `npm run dev`\n5. **尝试构建项目** - `npm run build`\n\n**如果还有错误，重复诊断-修复-验证流程，直到全部通过。**\n\n---\n\n## 修复优先级原则\n\n1. **正确性优先** - 保证修复后的代码逻辑正确\n2. **最小改动** - 只修改必要的部分，不引入无关变更\n3. **保留语义** - 修复后代码的行为应和原意图一致\n4. **可维护性** - 修复方案应清晰易懂，不是黑魔法\n\n---\n\n*本策略库基于 100+ 实际项目问题总结而成，持续更新中...*\n\nFile v1.0.3:references/standards.md\n\n# 详细文件结构与命名规范\n\n## 目录\n\n- [Next.js 项目标准结构](#nextjs-项目标准结构)\n- [Node.js 后端项目结构](#nodejs-后端项目结构)\n- [React 组件库项目结构](#react-组件库项目结构)\n- [命名规范](#命名规范)\n- [Git 提交规范](#git-提交规范)\n\n---\n\n## Next.js 项目标准结构\n\n### 完整目录树\n\n```\nproject-name/\n├── app/ # App Router 目录\n│ ├── (auth)/ # 路由组 - 认证相关\n│ │ ├── login/\n│ │ │ └── page.tsx\n│ │ └── register/\n│ │ └── page.tsx\n│ ├── (dashboard)/ # 路由组 - 仪表板\n│ │ ├── layout.tsx\n│ │ └── page.tsx\n│ ├── api/ # API 路由\n│ │ └── hello/\n│ │ └── route.ts\n│ ├── layout.tsx # 根布局\n│ ├── page.tsx # 首页\n│ └── globals.css # 全局样式\n├── components/ # 可复用组件\n│ ├── ui/ # 基础 UI 组件 (Button, Input, etc.)\n│ │ ├── button.tsx\n│ │ └── input.tsx\n│ ├── layout/ # 布局组件\n│ │ ├── header.tsx\n│ │ └── sidebar.tsx\n│ └── features/ # 业务组件\n│ └── user-profile.tsx\n├── lib/ # 工具库\n│ ├── utils/ # 通用工具函数\n│ │ └── format.ts\n│ ├── hooks/ # 自定义 Hooks\n│ │ └── use-local-storage.ts\n│ ├── types/ # TypeScript 类型定义\n│ │ └── index.ts\n│ └── clients/ # 第三方客户端\n│ ├── supabase.ts\n│ └── openai.ts\n├── public/ # 静态资源\n│ ├── images/\n│ ├── icons/\n│ └── favicon.ico\n├── styles/ # 样式文件\n│ └── theme.css\n├── .env.example # 环境变量示例\n├── .env.local # 本地环境变量 (gitignore)\n├── .gitignore\n├── package.json\n├── pnpm-lock.yaml / package-lock.json\n├── tsconfig.json\n├── next.config.js\n├── tailwind.config.js (可选)\n├── README.md\n└── *-init.sql # 数据库初始化SQL\n```\n\n### 文件命名规则\n\n| 类型 | 命名规范 | 示例 |\n|------|---------|------|\n| 页面组件 | kebab-case + page.tsx | `user-profile/page.tsx` |\n| UI 组件 | PascalCase | `Button.tsx`, `UserCard.tsx` |\n| Hook 函数 | camelCase, use- 前缀 | `use-local-storage.ts` |\n| 工具函数 | camelCase | `format-date.ts` |\n| 类型定义 | PascalCase | `User.ts`, `ApiResponse.ts` |\n| 配置文件 | dot notation | `.eslintrc.js`, `tailwind.config.js` |\n\n---\n\n## Node.js 后端项目结构\n\n```\nbackend-project/\n├── src/\n│ ├── controllers/ # 控制器层\n│ │ └── user.controller.ts\n│ ├── services/ # 业务逻辑层\n│ │ └── user.service.ts\n│ ├── repositories/ # 数据访问层\n│ │ └── user.repository.ts\n│ ├── routes/ # 路由定义\n│ │ └── user.routes.ts\n│ ├── middleware/ # 中间件\n│ │ └── auth.middleware.ts\n│ ├── models/ # 数据模型\n│ │ └── user.model.ts\n│ ├── types/ # 类型定义\n│ │ └── index.ts\n│ ├── utils/ # 工具函数\n│ │ └── validator.ts\n│ ├── config/ # 配置文件\n│ │ └── database.ts\n│ └── app.ts # 应用入口\n├── tests/ # 测试文件\n│ └── user.test.ts\n├── .env.example\n├── .gitignore\n├── package.json\n├── tsconfig.json\n└── README.md\n```\n\n---\n\n## React 组件库项目结构\n\n```\ncomponent-library/\n├── src/\n│ ├── components/\n│ │ ├── Button/\n│ │ │ ├── Button.tsx\n│ │ │ ├── Button.test.tsx\n│ │ │ ├── Button.stories.tsx\n│ │ │ └── index.ts\n│ │ └── Input/\n│ │ ├── Input.tsx\n│ │ ├── Input.test.tsx\n│ │ ├── Input.stories.tsx\n│ │ └── index.ts\n│ ├── hooks/\n│ ├── utils/\n│ ├── styles/\n│ └── index.ts # 库入口\n├── .env.example\n├── .gitignore\n├── package.json\n├── tsconfig.json\n├── vite.config.ts (可选)\n└── README.md\n```\n\n---\n\n## 命名规范\n\n### 通用原则\n\n1. **语义化** - 名称要能准确表达用途\n2. **一致性** - 同一类事物用相同命名模式\n3. **简洁性** - 不使用冗余词汇，不缩写到难以理解\n\n### 文件命名\n\n| 类型 | 规范 | 正确示例 | 错误示例 |\n|------|------|---------|---------|\n| React 组件 | PascalCase | `UserProfile.tsx` | `userProfile.tsx`, `user_profile.tsx` |\n| 普通模块 | kebab-case | `auth-utils.ts` | `authUtils.ts`, `AuthUtils.ts` |\n| Hook 文件 | kebab-case, use- 前缀 | `use-click-outside.ts` | `UseClickOutside.ts` |\n| 类型定义 | PascalCase | `UserProfile.ts` | `user-profile.ts` |\n| 配置文件 | dot notation | `.eslintrc.js` | `eslintrc.js` |\n| 图片资源 | kebab-case | `hero-banner.png` | `HeroBanner.png` |\n\n### 代码命名\n\n| 类型 | 规范 | 正确示例 | 错误示例 |\n|------|------|---------|---------|\n| 类/组件 | PascalCase | `class UserService {}` | `class userService {}` |\n| 函数/方法 | camelCase | `function getUser() {}` | `function GetUser() {}` |\n| 变量 | camelCase | `const userName = 'xxx'` | `const UserName = 'xxx'` |\n| 常量 | UPPER_SNAKE_CASE | `const MAX_RETRY = 3` | `const maxRetry = 3` |\n| 接口/类型 | PascalCase | `interface User {}` | `interface user {}` |\n| 枚举 | PascalCase | `enum Status {}` | `enum STATUS {}` |\n\n### React 特有命名\n\n| 类型 | 规范 | 示例 |\n|------|------|------|\n| 组件名 | PascalCase | `UserProfile`, `Button` |\n| Props 接口 | `ComponentNameProps` | `UserProfileProps`, `ButtonProps` |\n| Hook 函数 | camelCase, use 前缀 | `useLocalStorage`, `useDebounce` |\n| 事件处理 | `handle` + 名词 + 动词 | `handleSubmitClick`, `handleInputChange` |\n\n---\n\n## Git 提交规范\n\n### 提交信息格式\n\n```\n(): \n\n\n\n