devassist-agent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevAssist Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,467 @@
+# DevAssist Agent
+
+**AI 辅助开发的质量守护智能体** — 从88条故障经验中提炼的开发辅助工具，防止代码腐化、局部优化、约定遗忘。
+
+## 架构概览
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    DevAssist Agent                          │
+├─────────────────┬──────────────────┬────────────────────────┤
+│  Layer 1        │  Layer 2         │  Layer 3               │
+│  开发时检查      │  运行时基础设施    │  AI 大模型接口          │
+│  (CLI + hooks)  │  (base code)     │  (增强分析)             │
+├─────────────────┼──────────────────┼────────────────────────┤
+│ ConventionStore │ ToolRegistry     │ AI Adapter             │
+│ SchemaRegistry  │ ChannelAgent     │ ├─ 通义千问 (Qwen)      │
+│ ImpactAnalyzer  │ ChannelMiddleware│ ├─ OpenAI (GPT)        │
+│ TechDebtTracker │ InfrastructureGuard│ ├─ Claude (Anthropic)  │
+│ CodeQualityGuard│ NotificationCenter│ └─ 混元 (Hunyuan)      │
+│ ArchRiskAssessor│ SchemaGatekeeper │ 规则引擎先跑 → AI增强    │
+│ PreDeployGuard  │                  │                       │
+│ VersionManager  │                  │                       │
+└─────────────────┴──────────────────┴────────────────────────┘
+```
+
+## 安装
+
+```bash
+# 全局安装（推荐）
+npm install -g devassist-agent
+
+# 或项目内安装
+npm install --save-dev devassist-agent
+
+# 验证安装
+devassist --version
+```
+
+## .devassistignore
+
+项目根目录可放置 `.devassistignore` 文件（格式类似 `.gitignore`），列出扫描时需跳过的目录和文件：
+
+```gitignore
+# 备份/归档目录
+*_backup/
+*_old/
+
+# 依赖
+node_modules/
+
+# 构建输出
+dist/
+build/
+```
+
+## 快速开始
+
+```bash
+# 1. 初始化项目（创建 .devassist/ 配置 + git hooks）
+devassist init
+
+# 2. 初始化并安装运行时基础设施（base code）
+devassist init --base-code
+
+# 3. 扫描代码质量
+devassist check
+
+# 4. 带 AI 深度分析扫描
+devassist check --ai
+
+# 5. 部署前检查
+devassist deploy --check
+
+# 6. 查看技术债看板
+devassist debt --scan
+
+# 7. 注册约定
+devassist convention add "前端禁止ES6+语法" --category code --severity block
+
+# 8. 注册 DB Schema
+devassist schema import schema.sql
+
+# 9. 增量备份
+devassist backup "发布前备份"
+
+# 10. AI 问答
+devassist ask "这个函数的圈复杂度是否过高？"
+
+# 11. 配置 AI（通义千问）
+devassist ai --setup --provider qwen --key sk-xxxx
+devassist ai --test
+
+# 12. 生成约定文件供 AI Agent 读取
+devassist inject --format all
+
+# 13. 环境诊断
+devassist doctor
+
+# 14. 清理旧报告和备份
+devassist clean --days 30
+
+# 15. 自动修复常见问题（预览模式）
+devassist fix --all --dry-run
+```
+
+## CLI 命令
+
+| 命令 | 说明 | 示例 |
+|------|------|------|
+| `init` | 初始化项目 | `devassist init --base-code` |
+| `check` | 代码质量扫描 | `devassist check --ai` |
+| `watch` | 实时监控文件变更 | `devassist watch --ai` |
+| `diff` | 只检查变更文件 (CI模式) | `devassist diff --staged` |
+| `report` | 生成 HTML 检查报告 | `devassist report --open` |
+| `deploy` | 部署前检查 | `devassist deploy --check` |
+| `debt` | 技术债看板 | `devassist debt --scan` |
+| `convention` | 约定管理 | `devassist convention list` |
+| `schema` | Schema 管理 | `devassist schema import db.sql` |
+| `backup` | 增量备份 | `devassist backup "v1.2"` |
+| `restore` | 非破坏性恢复 | `devassist restore v-2026-07-22` |
+| `ask` | AI 问答 | `devassist ask "分析这段代码"` |
+| `ai` | AI 配置与测试 | `devassist ai --setup --provider qwen --key sk-xxx` |
+| `inject` | 生成约定文件 | `devassist inject --format cursor` |
+| `doctor` | 环境诊断 | `devassist doctor` |
+| `clean` | 清理旧文件 | `devassist clean --days 30` |
+| `fix` | 自动修复 | `devassist fix --all --dry-run` |
+| `help` | 帮助 | `devassist help` |
+
+## Layer 1：开发时检查模块
+
+### ConventionStore（约定记忆库）
+防止 AI 遗忘早期约定。所有约定持久化存储，每次检查自动匹配。
+```json
+// .devassist/conventions.json
+{
+  "conventions": [
+    {
+      "id": "naming-list-key",
+      "rule": "列表数据必须使用 data.list，不用 data.items 或 data.records",
+      "forbid": "data\\.(items|records)\\s*[=:]", 
+      "severity": "block"
+    }
+  ]
+}
+```
+
+### ImpactAnalyzer（影响分析器）
+防止 Agent 局部优化打补丁。修改文件前分析影响范围，检测大规模代码缩减。
+- 依赖图分析：修改 app.js → 标记所有依赖文件
+- 行数缩减阻断：2720行 → 106行 → 危险！阻断
+- 补丁检测：前端兼容代码 → 建议改后端
+
+### SchemaRegistry（Schema 注册中心）
+防止代码库腐化。追踪 DB 表结构和 API 契约的版本变化。
+- DDL 导入：35 张表结构自动解析
+- 漂移检测：容器内加字段未同步源码 → 告警
+- API 契约：注册了 data.list，返回 data.items → 阻断
+
+### CodeQualityGuard（代码质量守护）
+30 条规则，覆盖安全漏洞、性能反模式、代码缺陷三大维度：
+
+**安全漏洞检测（8 条）**
+- `sec-eval-usage` — eval/Function 代码注入 (block)
+- `sec-sql-injection` — SQL 字符串拼接注入 (block)
+- `sec-hardcoded-secrets` — 硬编码密钥/密码/Token (block)
+- `sec-path-traversal` — 用户输入拼入文件路径 (warn)
+- `sec-command-injection` — exec/spawn 字符串拼接 (block)
+- `sec-insecure-crypto` — MD5/SHA1 弱哈希、Math.random 安全场景 (warn)
+- `sec-xss-risk` — innerHTML/document.write XSS (block)
+- `sec-proto-pollution` — Object.assign 原型链污染 (warn)
+
+**性能反模式检测（6 条）**
+- `perf-sync-io-in-async` — 异步函数中同步 I/O 阻塞事件循环 (warn)
+- `perf-n-plus-1` — 循环内 await N+1 查询 (warn)
+- `perf-string-concat-loop` — 循环内字符串拼接 O(n²) (info)
+- `perf-regex-in-loop` — 循环内重复编译正则 (info)
+- `perf-json-parse-unsafe` — JSON.parse 无 try/catch (warn)
+- `perf-no-pagination` — 无分页全表查询 (warn)
+
+**代码缺陷检测（16 条）**
+- null 安全检查（深层属性链未判空）
+- 时序竞态检测（DOMContentLoaded 前绑定事件）
+- 重复声明检测（作用域感知）
+- 文件过大检测（默认 800 行上限）
+- ID/Class 混淆检测
+- await 未被 try/catch 包裹
+- **API 响应键名漂移检测**（data.list vs data.items vs data.records → BLOCK）
+- **fetch 缺少错误处理**（无 .catch() 的 fetch 调用）
+- **硬编码配置值**（端口/URL 硬编码）
+- **console.log 残留**（生产代码调试日志）
+- **async 调用缺少 await**（Promise 被丢弃）
+- **事件监听无清理**（addEventListener 无 removeEventListener）
+- **TODO/FIXME 堆积**（技术债务标记积累）
+- **魔法数字**（硬编码数值常量）
+- **错误响应格式不一致**（code+msg vs code+message vs error:string）
+- **危险文件覆盖检测**（fs.writeFileSync 写入大段字符串）
+
+### ArchRiskAssessor（架构风险评估）
+- 过度设计预警（代码行数 vs 问题复杂度比值）
+- 恢复循环检测（catch 块中的直接自调用）
+- 远程代码注入风险检测
+
+### PreDeployGuard（部署前检查）
+- 端口冲突检测（防 supervisord 抢 8080）
+- MIME 类型验证、路由规则验证
+- 部署清单 checklist、Cache-Busting 检查
+
+### TechDebtTracker（技术债追踪）
+- 每周扫描复杂度、耦合度、重复率
+- 自动排序"下一个该还的债"
+
+### VersionManager（版本备份）
+- 增量备份（只备份变更文件）
+- 非破坏性恢复（恢复前预警将丢失的文件）
+
+## Layer 2：运行时基础设施
+
+安装方式：`devassist init --base-code`
+
+### ToolRegistry（工具注册中心）
+零升级架构核心。新功能以 tool 模块动态注册，无需重新编译。
+```javascript
+const { registry, MODULE_TYPES } = require('./lib');
+
+await registry.register({
+  id: 'weather.query',
+  name: 'Weather Query',
+  version: '1.0.0',
+  type: MODULE_TYPES.DYNAMIC,
+  category: 'weather',
+  schema: {
+    input: { required: ['city'], properties: { city: 'string' } },
+    output: { required: ['temp'], properties: { temp: 'number' } },
+  },
+  handler: async (input) => ({ temp: 25, city: input.city }),
+});
+```
+
+### ChannelAgent（服务端协议处理器）
+接收客户端协议消息，HMAC 签名验证，路由到 ToolRegistry。
+```
+客户端: { protocol, seq, action, timestamp, token, payload, signature }
+                          ↓
+                    ChannelAgent.handleRequest()
+                          ↓
+                    ActionRouter → ToolRegistry.invoke()
+                          ↓
+服务端: { protocol, code, data, message, seq, timestamp }
+```
+
+### ChannelMiddleware（中间件链）
+Koa 风格的洋葱模型中间件：
+- `errorHandler()` — 错误捕获
+- `requestLogger()` — 请求日志
+- `authGuard()` — JWT 认证
+- `rateLimiter()` — 滑动窗口限流
+- `schemaValidator()` — 输入校验
+- `corsHandler()` — CORS 处理
+
+### InfrastructureGuard（健康监控）
+5 探针 + 自适应频率 + FSM 状态机：
+- HttpProbe — HTTP 端点存活检查
+- DatabaseProbe — 数据库连接检查
+- MemoryProbe — 堆内存/RSS 监控
+- DiskProbe — 磁盘空间检查
+- ProcessProbe — 子进程存活检查
+
+状态流转：`HEALTHY → DEGRADED → UNHEALTHY → RECOVERING → HEALTHY`
+
+### NotificationCenter（通知中心）
+4 通道 + 优先级路由 + 去重 + 限流：
+- LogChannel — 控制台/文件日志
+- EmailChannel — 邮件通知
+- WebhookChannel — HTTP Webhook
+- DingTalkChannel — 钉钉群机器人
+
+### SchemaGatekeeper（运行时协议守门）
+4 层防御，15 条规则：
+1. **语法层**：JSON 可序列化、无循环引用、无 undefined
+2. **Schema 层**：必填检查、类型匹配、长度/范围校验
+3. **语义层**：响应信封检查、字段命名一致性
+4. **安全层**：SQL 注入、XSS、路径穿越、命令注入、敏感字段泄露
+
+## Layer 3：AI 大模型接口
+
+**设计原则：规则引擎是主，AI 是增强层，不是替代层。**
+
+```
+规则引擎先跑（零延迟、可预测）
+    ↓ 发现疑似问题
+AI 深度分析（根因 + 修复建议 + 置信度）
+    ↓ AI 不可达时
+降级：仅返回规则引擎结果，标注 "AI 分析不可用"
+```
+
+支持 4 个 provider：
+- 通义千问（Qwen / DashScope）
+- OpenAI（GPT-4 / GPT-3.5）
+- Claude（Anthropic）
+- 腾讯混元（Hunyuan / TokenHub）
+
+支持多引擎并行分析（N 引擎可扩展），对比不同 AI 的判断结果，不一致项自动标记"待观察"。
+
+### AI 配置
+
+```bash
+# 方式一：命令行配置（推荐）
+devassist ai --setup --provider qwen --key sk-xxxx
+devassist ai --test          # 测试连通性
+devassist ai --status        # 查看配置状态
+
+# 方式二：环境变量
+export DASHSCOPE_API_KEY=sk-xxxx    # 通义千问
+export HUNYUAN_API_KEY=sk-xxxx      # 腾讯混元
+
+# 方式三：编辑 .devassist/ai-config.json
+```
+
+### AI 深度分析
+
+```bash
+# 扫描并对 warn/block 级别发现做 AI 根因分析
+devassist check --ai
+
+# 单独分析最近一次 check 的结果
+devassist ai --analyze
+
+# 向 AI 提问
+devassist ask "为什么 API 返回 data.items 而不是 data.list？"
+```
+
+AI 返回结构化分析：根因、是否误报、修复建议、代码示例、置信度。
+
+### 约定自动注入（Convention Injection）
+
+核心差异化能力——让 AI Agent 在写代码时自动获取项目约定：
+
+```bash
+# 生成 .devassist/CONVENTIONS.md（Markdown 格式，AI Agent 自动发现）
+devassist inject --format markdown
+
+# 生成 .cursorrules（Cursor 读取）
+devassist inject --format cursor
+
+# 生成 .traerules（Trae 读取）
+devassist inject --format trae
+
+# 一次性生成所有格式
+devassist inject --format all
+```
+
+工作原理：AI Agent（Trae/WorkBuddy/Cursor）在开始写代码前会读取项目根目录的规则文件。`inject` 命令将 `.devassist/conventions.json` 中的约定同步到这些文件，确保 AI 始终知道项目约定。每次更新约定后重新运行 `inject` 即可同步。
+
+## 测试
+
+```bash
+# 全部测试（59 项）
+node tests/run-all.js
+
+# Layer 2 集成测试（69 项）
+node tests/test-layer2.js
+```
+
+**总计：128 项测试，全部通过。**
+
+## 项目结构
+
+```
+devassist/
+├── bin/
+│   └── devassist.js              # CLI 入口
+├── src/
+│   ├── core/                      # 核心引擎
+│   │   ├── event-bus.js           # 事件总线
+│   │   ├── fsm.js                 # 状态机（含无限循环保护）
+│   │   ├── rule-engine.js         # 规则引擎
+│   │   └── logger.js              # 结构化日志
+│   ├── modules/
+│   │   ├── dev-time/              # Layer 1: 开发时模块
+│   │   │   ├── convention-store.js
+│   │   │   ├── schema-registry.js
+│   │   │   ├── impact-analyzer.js
+│   │   │   ├── tech-debt-tracker.js
+│   │   │   ├── code-quality-guard.js
+│   │   │   ├── arch-risk-assessor.js
+│   │   │   ├── pre-deploy-guard.js
+│   │   │   └── version-manager.js
+│   │   └── runtime/               # Layer 2: 运行时模块
+│   │       ├── tool-registry.js
+│   │       ├── channel-agent.js
+│   │       ├── channel-middleware.js
+│   │       ├── infrastructure-guard.js
+│   │       ├── notification-center.js
+│   │       ├── schema-gatekeeper.js
+│   │       └── index.js
+│   ├── ai/                        # Layer 3: AI 接口
+│   │   ├── adapter.js             # 统一适配器
+│   │   └── providers/
+│   │       ├── qwen.js            # 通义千问
+│   │       ├── openai.js          # OpenAI
+│   │       ├── claude.js          # Claude
+│   │       └── hunyuan.js         # 腾讯混元
+│   ├── cli/
+│   │   ├── commands/              # CLI 命令
+│   │   │   ├── init.js
+│   │   │   ├── check.js
+│   │   │   ├── watch.js               # 实时监控
+│   │   │   ├── diff.js                # CI 增量检查
+│   │   │   ├── report.js              # HTML 报告
+│   │   │   ├── deploy.js
+│   │   │   ├── debt.js
+│   │   │   ├── convention.js
+│   │   │   ├── schema.js
+│   │   │   ├── backup.js
+│   │   │   ├── restore.js
+│   │   │   ├── ask.js
+│   │   │   ├── ai.js                  # AI 配置与测试
+│   │   │   ├── inject.js              # 约定注入（生成 .cursorrules 等）
+│   │   │   ├── doctor.js              # 环境诊断
+│   │   │   ├── clean.js               # 清理旧文件
+│   │   │   └── fix.js                 # 自动修复
+│   │   └── shared/                # 公共模块
+│   │       ├── file-collector.js      # 文件收集（collectFiles/walkDir）
+│   │       ├── config-loader.js       # 项目配置加载（.devassist/config.json）
+│   │       ├── inline-ignore.js       # 行内忽略注释处理
+│   │       └── code-context.js        # AI 代码上下文提取
+│   └── index.js                   # 统一导出
+├── templates/
+│   ├── git-hooks/
+│   │   └── pre-commit             # Git pre-commit hook
+│   └── ci/
+│       ├── github-actions.yml     # GitHub Actions CI 模板
+│       ├── gitlab-ci.yml          # GitLab CI 模板
+│       └── pre-commit-hook.sh     # pre-commit hook 模板
+├── tests/
+│   ├── run-all.js                 # Layer 1 测试
+│   └── test-layer2.js             # Layer 2 集成测试
+└── package.json
+```
+
+## 防御故障覆盖
+
+基于小麦AI助手 88 条故障报告的分析：
+
+| 痛点 | 命中故障 | 防御模块 |
+|------|---------|---------|
+| 局部优化 | 41/88 | ImpactAnalyzer |
+| 代码库腐化 | 35/88 | SchemaRegistry + ConventionStore |
+| 记忆碎片化 | 32/88 | ConventionStore (ADR) |
+| 重构成本高 | 23/88 | TechDebtTracker |
+| 代码缺陷 | 33% | CodeQualityGuard |
+| 部署配置 | 27% | PreDeployGuard |
+| 架构设计 | 20% | ArchRiskAssessor |
+| 文件管理 | 13% | VersionManager |
+
+**对 10 个严重故障防御覆盖率：100%**
+
+## 零外部依赖
+
+整个项目不依赖任何 npm 包，仅使用 Node.js 内置模块（`crypto`, `os`, `fs`, `path`, `http`）。这意味着：
+- 安装即用，无需 `npm install`
+- 不会引入安全漏洞
+- 不会因依赖更新而破坏
+
+## License
+
+MIT