artifact-chain-assistant 0.8.0

package/adapters/codex/templates/extended/contracts/batch_job_contract/starter.md

@@ -0,0 +1,158 @@
+---
+id: {BATCH_ID}
+title: {批处理作业名称}
+status: draft
+version: {v1}
+schedule: {调度表达式}
+related_features: []
+---
+
+# {BATCH_ID}: {批处理作业名称}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+<!-- 插件模板是入门指导，项目本地模板是权威 -->
+
+## 概述
+
+{描述这个批处理作业的用途、业务场景和主要功能}
+
+## 基础信息
+
+- **版本**：{version}
+- **调度表达式**：{cron 表达式，如 "0 2 * * ?" 表示每天凌晨 2 点}
+- **执行环境**：本地 / K8s CronJob / Airflow / XXL-Job / ElasticJob
+- **超时时间**：{作业最大执行时长}
+- **失败重试**：{是否支持失败重试，最大重试次数}
+
+## 输入定义
+
+### 数据源
+
+| 数据源 | 类型 | 位置 | 说明 |
+|--------|------|------|------|
+| {数据源名称} | 数据库 / 文件 / API / 消息队列 | {位置} | {说明} |
+
+### 输入参数
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|-------|------|
+| {param_name} | {type} | 是/否 | {default} | {参数描述} |
+
+### 输入格式
+
+```
+{输入数据的格式示例}
+```
+
+## 输出定义
+
+### 输出目标
+
+| 目标 | 类型 | 位置 | 说明 |
+|------|------|------|------|
+| {目标名称} | 数据库 / 文件 / API / 消息队列 | {位置} | {说明} |
+
+### 输出参数
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| {param_name} | {type} | {参数描述} |
+
+### 输出格式
+
+```
+{输出数据的格式示例}
+```
+
+## 处理逻辑
+
+### 主流程
+
+1. {步骤 1：描述}
+2. {步骤 2：描述}
+3. {步骤 3：描述}
+
+### 分片策略
+
+- **分片方式**：{按 ID 范围 / 按时间范围 / 按哈希}
+- **分片大小**：{每片处理的数据量}
+- **并行度**：{最大并行分片数}
+
+### 过滤条件
+
+| 条件 | 字段 | 运算符 | 值 | 说明 |
+|------|------|--------|-----|------|
+| {条件名称} | {field} | = / != / > / < / IN | {value} | {条件描述} |
+
+## 幂等性
+
+- **幂等策略**：{唯一键去重 / 状态检查 / 版本号}
+- **唯一键**：{唯一键的组成字段}
+- **冲突处理**：{跳过 / 覆盖 / 报错}
+- **重复执行**：{是否支持重复执行，重复执行的行为}
+
+## 错误处理
+
+### 错误分类
+
+| 错误类型 | 示例 | 处理策略 |
+|---------|------|---------|
+| 数据错误 | 格式错误、校验失败 | 跳过 + 记录错误日志 |
+| 系统错误 | 数据库连接失败、磁盘满 | 重试 + 告警 |
+| 业务错误 | 状态冲突、业务规则不满足 | 记录 + 人工介入 |
+
+### 错误记录
+
+- **错误日志位置**：{错误日志的存储位置}
+- **错误数据存储**：{错误数据的存储位置，如"错误表 / 错误文件"}
+- **错误报告**：{错误汇总报告的生成方式}
+
+### 失败处理
+
+- **单条失败**：{跳过 / 终止 / 回滚}
+- **批量失败**：{告警阈值、处理策略}
+- **作业失败**：{重试策略、告警方式}
+
+## 监控与告警
+
+### 监控指标
+
+| 指标名称 | 类型 | 说明 |
+|---------|------|------|
+| 处理总量 | Counter | {说明} |
+| 成功数量 | Counter | {说明} |
+| 失败数量 | Counter | {说明} |
+| 处理时长 | Histogram | {说明} |
+| 处理速率 | Gauge | {说明} |
+
+### 告警规则
+
+| 告警名称 | 条件 | 级别 | 通知方式 |
+|---------|------|------|---------|
+| {告警名称} | {条件} | P0 / P1 / P2 | {钉钉 / 邮件 / 短信} |
+
+## 性能要求
+
+- **预期数据量**：{每次处理的数据量}
+- **处理时间要求**：{最大允许处理时间}
+- **资源限制**：{CPU / 内存 / 磁盘限制}
+
+## 回滚策略
+
+- **回滚条件**：{什么情况下需要回滚}
+- **回滚方式**：{手动 / 自动}
+- **回滚步骤**：{回滚的具体步骤}
+- **数据一致性**：{如何保证回滚后的数据一致性}
+
+## 关联制品
+
+- 功能特性：{related_features}
+- 设计文档：{related_designs}
+- 决策：{related_decisions}
+- 数据契约：{related_data_contracts}
+
+## 变更日志
+
+| 日期 | 版本 | 变更 | 作者 |
+|------|------|------|------|
+| {YYYY-MM-DD} | v1 | 初始版本 | {作者} |

package/adapters/codex/templates/extended/contracts/cli_contract/review-checklist.md

@@ -0,0 +1,43 @@
+# CLI Contract 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式（如 `CLI-{nnn}` 或 `{tool}-CLI-{version}`）
+- [ ] `title` 清晰描述 CLI 工具
+- [ ] `version` 字段存在且符合语义化版本
+- [ ] 命令结构层级清晰
+
+## 命令质量
+
+- [ ] 每个命令有清晰描述
+- [ ] 选项和参数类型明确
+- [ ] 必填/可选标识正确
+- [ ] 默认值已说明
+
+## 用户体验
+
+- [ ] 帮助文本准确
+- [ ] 错误信息有指导性
+- [ ] 退出码语义明确
+- [ ] 示例覆盖常见场景
+
+## 向后兼容
+
+- [ ] 破坏性变更已记录
+- [ ] 废弃选项有迁移路径
+- [ ] 版本升级指南存在
+
+## 追溯性
+
+- [ ] 关联功能特性存在
+- [ ] 命令可追溯到用户需求
+- [ ] 版本变更可追溯
+
+## 实现一致性
+
+- [ ] 与实现代码一致
+- [ ] 文档与实际行为匹配
+- [ ] 测试覆盖所有命令
+- [ ] 自动补全配置正确（如适用）

package/adapters/codex/templates/extended/contracts/cli_contract/starter.md

@@ -0,0 +1,93 @@
+---
+id: {CLI_ID}
+title: {CLI 工具名称}
+status: draft
+version: {v1}
+related_features: []
+---
+
+# {CLI_ID}: {CLI 工具名称}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+<!-- 插件模板是入门指导，项目本地模板是权威 -->
+
+## 概述
+
+{描述这个 CLI 工具的用途、目标用户和主要能力}
+
+## 基础信息
+
+- **版本**：{version}
+- **命令名称**：{command}
+- **安装方式**：{npm/pip/binary}
+
+## 命令结构
+
+```bash
+{command} [全局选项] <命令> [命令选项] [参数]
+```
+
+## 全局选项
+
+| 选项 | 简写 | 描述 | 默认值 |
+|------|------|------|--------|
+| --help | -h | 显示帮助 | - |
+| --version | -v | 显示版本 | - |
+| --verbose | | 详细输出 | false |
+
+## 命令列表
+
+### {command} {子命令}
+
+**描述**：{命令描述}
+
+**用法**：
+```bash
+{command} {子命令} [选项] <参数>
+```
+
+**选项**：
+
+| 选项 | 简写 | 描述 | 默认值 |
+|------|------|------|--------|
+| --option1 | -o | {描述} | {默认值} |
+
+**参数**：
+
+| 参数 | 必填 | 描述 |
+|------|------|------|
+| {param} | {yes/no} | {描述} |
+
+**示例**：
+```bash
+{command} {子命令} --option1 value arg1
+```
+
+**退出码**：
+
+| 退出码 | 描述 |
+|--------|------|
+| 0 | 成功 |
+| 1 | 一般错误 |
+| 2 | 参数错误 |
+
+## 配置文件
+
+{描述配置文件位置、格式和选项}
+
+## 环境变量
+
+| 变量 | 描述 | 优先级 |
+|------|------|--------|
+| {VAR_NAME} | {描述} | {高于/低于}配置文件 |
+
+## 关联制品
+
+- 功能特性：{related_features}
+- 设计文档：{related_designs}
+
+## 变更日志
+
+| 日期 | 版本 | 变更 | 作者 |
+|------|------|------|------|
+| {YYYY-MM-DD} | v1 | 初始版本 | {作者} |

package/adapters/codex/templates/extended/contracts/data_contract/review-checklist.md

@@ -0,0 +1,45 @@
+# Data Contract 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式（如 `DATA-{nnn}`）
+- [ ] `title` 清晰描述数据契约范围
+- [ ] `version` 字段存在且符合语义化版本
+- [ ] 数据格式已指定
+
+## 数据模型质量
+
+- [ ] Schema 定义完整
+- [ ] 字段类型和约束明确
+- [ ] 必填/可选标识正确
+- [ ] 枚举值有文档说明
+
+## 数据质量
+
+- [ ] 数据质量规则已定义
+- [ ] 验证方法可执行
+- [ ] 监控指标已配置
+- [ ] 告警阈值已设定
+
+## 版本兼容性
+
+- [ ] 兼容变更规则明确
+- [ ] 破坏性变更已记录
+- [ ] 迁移路径已规划
+- [ ] 版本升级指南存在
+
+## 追溯性
+
+- [ ] 关联功能特性存在
+- [ ] 数据生产者已识别
+- [ ] 数据消费者已识别
+- [ ] 数据血缘可追溯
+
+## 实现一致性
+
+- [ ] 与实际数据格式一致
+- [ ] 文档与实现匹配
+- [ ] 测试覆盖所有字段
+- [ ] 数据验证已集成

package/adapters/codex/templates/extended/contracts/data_contract/starter.md

@@ -0,0 +1,88 @@
+---
+id: {DATA_ID}
+title: {数据契约名称}
+status: draft
+version: {v1}
+related_features: []
+---
+
+# {DATA_ID}: {数据契约名称}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+<!-- 插件模板是入门指导，项目本地模板是权威 -->
+
+## 概述
+
+{描述这个数据契约的用途、数据来源和消费方}
+
+## 基础信息
+
+- **版本**：{version}
+- **数据格式**：JSON / Avro / Protobuf / Parquet
+- **生产者**：{数据生产服务}
+- **消费者**：{数据消费服务列表}
+
+## 数据模型
+
+### Schema 定义
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "field1": {
+      "type": "string",
+      "description": "字段描述"
+    },
+    "field2": {
+      "type": "integer",
+      "minimum": 0
+    }
+  },
+  "required": ["field1"]
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 必填 | 描述 | 约束 |
+|------|------|------|------|------|
+| field1 | string | 是 | {描述} | max: 255 |
+| field2 | integer | 否 | {描述} | min: 0 |
+
+## 数据质量规则
+
+| 规则 | 描述 | 验证方式 |
+|------|------|---------|
+| 完整性 | {规则描述} | {验证方法} |
+| 一致性 | {规则描述} | {验证方法} |
+| 时效性 | {规则描述} | {验证方法} |
+
+## 版本兼容性
+
+### 兼容变更
+
+- 添加可选字段
+- 放宽字段约束
+
+### 破坏性变更
+
+- 删除字段
+- 修改字段类型
+- 收紧字段约束
+
+## 数据血缘
+
+{描述数据流转路径和依赖关系}
+
+## 关联制品
+
+- 功能特性：{related_features}
+- 设计文档：{related_designs}
+
+## 变更日志
+
+| 日期 | 版本 | 变更 | 作者 |
+|------|------|------|------|
+| {YYYY-MM-DD} | v1 | 初始版本 | {作者} |

package/adapters/codex/templates/extended/contracts/integration_contract/review-checklist.md

@@ -0,0 +1,77 @@
+# Integration Contract 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式（如 `INT-{nnn}`）
+- [ ] `title` 清晰描述集成范围
+- [ ] `version` 字段存在且符合语义化版本
+- [ ] `status` 字段存在且为有效值
+- [ ] `protocol` 字段存在且为有效协议
+- [ ] `external_system` 字段存在
+
+## 连接配置
+
+- [ ] 端点信息完整（开发 / 测试 / 生产）
+- [ ] 认证方式已说明
+- [ ] 凭证管理策略已定义
+- [ ] 超时配置已定义（连接 / 读取 / 写入）
+
+## 接口质量
+
+- [ ] 所有接口有清晰描述
+- [ ] 请求格式完整且示例正确
+- [ ] 响应格式完整且示例正确
+- [ ] 错误码覆盖常见异常场景
+- [ ] 错误处理策略已说明
+
+## 重试与熔断
+
+- [ ] 重试规则已定义（最大次数、间隔、退避策略）
+- [ ] 熔断配置已定义（阈值、时长、半开状态）
+- [ ] 重试场景已分类
+- [ ] 重试与熔断的边界已说明
+
+## 错误处理
+
+- [ ] 错误分类已定义（网络 / 认证 / 业务 / 系统）
+- [ ] 每类错误的处理策略已说明
+- [ ] 降级策略已定义
+- [ ] 降级触发条件已明确
+- [ ] 恢复策略已说明
+
+## 幂等性
+
+- [ ] 幂等键生成规则已定义
+- [ ] 幂等存储方案已说明
+- [ ] 幂等过期策略已定义
+- [ ] 幂等性边界已说明
+
+## 数据映射
+
+- [ ] 字段映射表完整
+- [ ] 类型转换规则已定义
+- [ ] 数据格式转换逻辑已说明
+- [ ] 枚举值映射已列出
+
+## 监控与告警
+
+- [ ] 关键监控指标已定义（成功率、响应时间、错误率）
+- [ ] 告警规则已定义
+- [ ] 告警级别和通知方式已说明
+- [ ] 监控阈值合理
+
+## 追溯性
+
+- [ ] 关联功能特性存在
+- [ ] 集成可追溯到业务需求
+- [ ] 版本变更可追溯
+- [ ] 关联设计文档存在
+
+## 实现一致性
+
+- [ ] 与实现代码一致
+- [ ] 文档与实际行为匹配
+- [ ] 测试覆盖核心场景
+- [ ] 性能满足要求

package/adapters/codex/templates/extended/contracts/integration_contract/starter.md

@@ -0,0 +1,158 @@
+---
+id: {INT_ID}
+title: {集成名称}
+status: draft
+version: {v1}
+protocol: {协议类型}
+external_system: {外部系统名称}
+related_features: []
+---
+
+# {INT_ID}: {集成名称}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+<!-- 插件模板是入门指导，项目本地模板是权威 -->
+
+## 概述
+
+{描述这个集成的目的、业务场景和主要能力}
+
+## 基础信息
+
+- **版本**：{version}
+- **协议**：REST / SOAP / gRPC / Message Queue / WebSocket / FTP / SFTP
+- **外部系统**：{外部系统名称和版本}
+- **环境**：开发 / 测试 / 预生产 / 生产
+- **SLA**：{服务等级协议，如"99.9% 可用性"}
+
+## 连接配置
+
+### 端点信息
+
+| 环境 | URL / 地址 | 端口 | 说明 |
+|------|-----------|------|------|
+| 开发 | {url} | {port} | {说明} |
+| 测试 | {url} | {port} | {说明} |
+| 生产 | {url} | {port} | {说明} |
+
+### 认证方式
+
+- **类型**：Basic Auth / OAuth2 / API Key / mTLS / JWT
+- **凭证管理**：{凭证存储位置，如"Vault / 环境变量"}
+- **刷新策略**：{Token 刷新策略，如"过期前 5 分钟自动刷新"}
+
+### 超时配置
+
+| 阶段 | 超时时间 | 说明 |
+|------|---------|------|
+| 连接建立 | {timeout} | {说明} |
+| 读取响应 | {timeout} | {说明} |
+| 写入数据 | {timeout} | {说明} |
+
+## 接口列表
+
+### {接口名称}
+
+**描述**：{接口用途}
+
+**请求**：
+
+```json
+{
+  "field1": "type",
+  "field2": "type"
+}
+```
+
+**响应**：
+
+```json
+{
+  "success": true,
+  "data": {}
+}
+```
+
+**错误码**：
+
+| 错误码 | 描述 | 处理策略 |
+|--------|------|---------|
+| {error_code} | {描述} | {重试 / 告警 / 降级} |
+
+## 重试策略
+
+### 重试规则
+
+| 场景 | 最大重试次数 | 重试间隔 | 退避策略 | 说明 |
+|------|------------|---------|---------|------|
+| {场景名称} | {次数} | {间隔} | 固定 / 指数 / 退避 | {说明} |
+
+### 熔断配置
+
+- **失败阈值**：{连续失败次数触发熔断}
+- **熔断时长**：{熔断持续时间}
+- **半开状态**：{半开状态下的试探请求数}
+
+## 错误处理
+
+### 错误分类
+
+| 错误类型 | 示例 | 处理策略 |
+|---------|------|---------|
+| 网络错误 | 连接超时、DNS 解析失败 | 重试 + 告警 |
+| 认证错误 | Token 过期、凭证无效 | 刷新凭证 + 重试 |
+| 业务错误 | 数据校验失败、状态冲突 | 记录日志 + 人工介入 |
+| 系统错误 | 服务不可用、限流 | 重试 + 熔断 + 降级 |
+
+### 降级策略
+
+- **降级触发条件**：{如"外部系统不可用超过 5 分钟"}
+- **降级行为**：{如"返回缓存数据 / 返回默认值 / 拒绝请求"}
+- **恢复策略**：{如"自动探测恢复 / 人工确认恢复"}
+
+## 幂等性
+
+- **幂等键**：{幂等键的生成规则，如"请求ID + 业务ID"}
+- **幂等存储**：{幂等键的存储位置，如"Redis / 数据库"}
+- **幂等过期**：{幂等键的过期时间}
+
+## 数据映射
+
+### 字段映射
+
+| 内部字段 | 外部字段 | 类型转换 | 说明 |
+|---------|---------|---------|------|
+| {internal_field} | {external_field} | {转换规则} | {说明} |
+
+### 数据转换
+
+{描述数据格式转换逻辑，如"日期格式转换、枚举值映射等"}
+
+## 监控与告警
+
+### 监控指标
+
+| 指标名称 | 类型 | 阈值 | 说明 |
+|---------|------|------|------|
+| 调用成功率 | Gauge | 99% | {说明} |
+| 响应时间 | Histogram | P99 < 500ms | {说明} |
+| 错误率 | Counter | < 1% | {说明} |
+
+### 告警规则
+
+| 告警名称 | 条件 | 级别 | 通知方式 |
+|---------|------|------|---------|
+| {告警名称} | {条件} | P0 / P1 / P2 | {钉钉 / 邮件 / 短信} |
+
+## 关联制品
+
+- 功能特性：{related_features}
+- 设计文档：{related_designs}
+- 决策：{related_decisions}
+- 数据契约：{related_data_contracts}
+
+## 变更日志
+
+| 日期 | 版本 | 变更 | 作者 |
+|------|------|------|------|
+| {YYYY-MM-DD} | v1 | 初始版本 | {作者} |