Compare commits
No commits in common. "816f036abed54a773224f00e7edc4e68e1527726" and "73d5c261b1fedf93588ff2be80437c63b500edc6" have entirely different histories.
816f036abe
...
73d5c261b1
|
|
@ -1,31 +1,29 @@
|
|||
#!/usr/bin/env python3
|
||||
import re
|
||||
import sys
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
from typing import Optional
|
||||
|
||||
PLAN_STATUS_START = "<!-- plan-status:start -->"
|
||||
PLAN_STATUS_END = "<!-- plan-status:end -->"
|
||||
PLAN_PREFIX = "[PLAN]"
|
||||
PLAN_SECTION_HEADER = "## Plan 状态记录"
|
||||
PLAN_FILE_RE = re.compile(r"^(\d{4}-\d{2}-\d{2})-.+\.md$")
|
||||
PLAN_LINE_RE = re.compile(
|
||||
r"^- \[(?P<check>[ xX])\] `(?P<plan>[^`]+)` (?P<status>done|blocked|pending)(?:: (?P<note>.*))?$"
|
||||
)
|
||||
VALID_STATUSES = {"done", "blocked", "pending"}
|
||||
VALID_STATUSES = {"in-progress", "done", "blocked"}
|
||||
|
||||
|
||||
def usage() -> str:
|
||||
return (
|
||||
"Usage:\n"
|
||||
" python scripts/plan_progress.py select -plans <dir> -progress <file>\n"
|
||||
" python scripts/plan_progress.py record -plan <path> -status <status> -progress <file> [-note <text>]\n"
|
||||
" python scripts/plan_progress.py -h\n"
|
||||
"Options:\n"
|
||||
" -plans DIR\n"
|
||||
" -plan PATH\n"
|
||||
" -status done|blocked|pending\n"
|
||||
" -progress FILE\n"
|
||||
" -note TEXT\n"
|
||||
" -h, -help Show this help.\n"
|
||||
"Usage:\\n"
|
||||
" python scripts/plan_progress.py select -plans <dir> -progress <file>\\n"
|
||||
" python scripts/plan_progress.py record -plan <path> -status <status> -progress <file> [-note <text>]\\n"
|
||||
" python scripts/plan_progress.py -h\\n"
|
||||
"Options:\\n"
|
||||
" -plans DIR\\n"
|
||||
" -plan PATH\\n"
|
||||
" -status in-progress|done|blocked\\n"
|
||||
" -progress FILE\\n"
|
||||
" -note TEXT\\n"
|
||||
" -h, -help Show this help.\\n"
|
||||
)
|
||||
|
||||
|
||||
|
|
@ -45,121 +43,100 @@ def parse_flags(args: list[str]) -> dict[str, str]:
|
|||
return flags
|
||||
|
||||
|
||||
def normalize_plan_key(plan_value: str) -> str:
|
||||
raw = plan_value.strip().replace("\\", "/")
|
||||
raw = raw.lstrip("./")
|
||||
if raw.startswith("docs/plans/"):
|
||||
return raw[len("docs/plans/") :]
|
||||
marker = "/docs/plans/"
|
||||
if marker in raw:
|
||||
return raw.split(marker, 1)[1]
|
||||
return raw
|
||||
def normalize_plan_key(plan_value: str, cwd: Path) -> str:
|
||||
try:
|
||||
return Path(plan_value).resolve().relative_to(cwd.resolve()).as_posix()
|
||||
except ValueError:
|
||||
return Path(plan_value).as_posix()
|
||||
|
||||
|
||||
def render_plan_line(plan_key: str, status: str, note: Optional[str]) -> str:
|
||||
checked = "x" if status == "done" else " "
|
||||
if status == "blocked":
|
||||
suffix = "blocked"
|
||||
if note:
|
||||
suffix += f": {note}"
|
||||
elif status == "pending":
|
||||
suffix = "pending"
|
||||
else:
|
||||
suffix = "done"
|
||||
return f"- [{checked}] `{plan_key}` {suffix}"
|
||||
def load_plan_records(progress_path: Path, cwd: Path) -> dict[str, str]:
|
||||
if not progress_path.exists():
|
||||
return {}
|
||||
text = progress_path.read_text(encoding="utf-8")
|
||||
records: dict[str, str] = {}
|
||||
for line in text.splitlines():
|
||||
if not line.startswith(PLAN_PREFIX):
|
||||
continue
|
||||
payload = line[len(PLAN_PREFIX) :].strip()
|
||||
if not payload:
|
||||
continue
|
||||
segments = [seg.strip() for seg in payload.split("|")]
|
||||
if not segments:
|
||||
continue
|
||||
plan_path = segments[0]
|
||||
status = None
|
||||
for seg in segments[1:]:
|
||||
if "=" not in seg:
|
||||
continue
|
||||
key, value = seg.split("=", 1)
|
||||
if key.strip() == "status":
|
||||
status = value.strip()
|
||||
if not plan_path or status is None:
|
||||
continue
|
||||
records[normalize_plan_key(plan_path, cwd)] = status
|
||||
return records
|
||||
|
||||
|
||||
def normalize_note(note: str) -> str:
|
||||
cleaned = note.replace("\n", " ").replace("\r", " ").replace("`", "'").strip()
|
||||
return cleaned
|
||||
|
||||
|
||||
def list_plan_files(plans_dir: Path) -> list[str]:
|
||||
entries: list[str] = []
|
||||
def list_plan_files(plans_dir: Path, cwd: Path) -> list[tuple[str, Path, str]]:
|
||||
entries: list[tuple[str, Path, str]] = []
|
||||
for path in plans_dir.iterdir():
|
||||
if not path.is_file():
|
||||
continue
|
||||
if not PLAN_FILE_RE.match(path.name):
|
||||
continue
|
||||
try:
|
||||
rel = path.resolve().relative_to(plans_dir.resolve()).as_posix()
|
||||
except ValueError:
|
||||
rel = path.name
|
||||
entries.append(rel)
|
||||
return sorted(entries)
|
||||
|
||||
|
||||
def find_block(lines: list[str]) -> Optional[tuple[int, int]]:
|
||||
start_idx = None
|
||||
for idx, line in enumerate(lines):
|
||||
if line.strip() == PLAN_STATUS_START:
|
||||
start_idx = idx
|
||||
break
|
||||
if start_idx is None:
|
||||
return None
|
||||
for idx in range(start_idx + 1, len(lines)):
|
||||
if lines[idx].strip() == PLAN_STATUS_END:
|
||||
return start_idx, idx
|
||||
return None
|
||||
|
||||
|
||||
def parse_entries(lines: list[str], start_idx: int, end_idx: int) -> list[tuple[str, str, Optional[str], int]]:
|
||||
entries: list[tuple[str, str, Optional[str], int]] = []
|
||||
for idx in range(start_idx + 1, end_idx):
|
||||
line = lines[idx].strip()
|
||||
match = PLAN_LINE_RE.match(line)
|
||||
match = PLAN_FILE_RE.match(path.name)
|
||||
if not match:
|
||||
continue
|
||||
plan_key = normalize_plan_key(match.group("plan"))
|
||||
status = match.group("status")
|
||||
note = match.group("note")
|
||||
entries.append((plan_key, status, note, idx))
|
||||
date_value = match.group(1)
|
||||
try:
|
||||
rel = path.resolve().relative_to(cwd.resolve()).as_posix()
|
||||
except ValueError:
|
||||
rel = path.as_posix()
|
||||
entries.append((date_value, path, rel))
|
||||
return entries
|
||||
|
||||
|
||||
def render_progress_lines(plans: list[str]) -> list[str]:
|
||||
lines = ["# Plan 状态", "", PLAN_STATUS_START]
|
||||
for plan_key in plans:
|
||||
lines.append(render_plan_line(plan_key, "pending", None))
|
||||
lines.append(PLAN_STATUS_END)
|
||||
return lines
|
||||
|
||||
|
||||
def select_plan(plans_dir: Path, progress_path: Path) -> tuple[int, str]:
|
||||
cwd = Path.cwd()
|
||||
if not plans_dir.is_dir():
|
||||
return 2, f"ERROR: plans dir not found: {plans_dir}"
|
||||
plan_keys = list_plan_files(plans_dir)
|
||||
if not plan_keys:
|
||||
plans = list_plan_files(plans_dir, cwd)
|
||||
if not plans:
|
||||
return 2, "ERROR: no plan files found"
|
||||
|
||||
progress_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
if progress_path.exists():
|
||||
lines = progress_path.read_text(encoding="utf-8").splitlines()
|
||||
else:
|
||||
lines = []
|
||||
records = load_plan_records(progress_path, cwd)
|
||||
|
||||
block = find_block(lines)
|
||||
if not block:
|
||||
lines = render_progress_lines(plan_keys)
|
||||
progress_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
|
||||
return 0, (plans_dir / plan_keys[0]).as_posix()
|
||||
in_progress = [item for item in plans if records.get(item[2]) == "in-progress"]
|
||||
if in_progress:
|
||||
in_progress.sort(key=lambda item: (item[0], item[2]))
|
||||
return 0, in_progress[-1][2]
|
||||
|
||||
start_idx, end_idx = block
|
||||
entries = parse_entries(lines, start_idx, end_idx)
|
||||
existing = {plan for plan, _, _, _ in entries}
|
||||
missing = [plan for plan in plan_keys if plan not in existing]
|
||||
if missing:
|
||||
insert_lines = [render_plan_line(plan, "pending", None) for plan in missing]
|
||||
lines[end_idx:end_idx] = insert_lines
|
||||
end_idx += len(insert_lines)
|
||||
progress_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
|
||||
entries = parse_entries(lines, start_idx, end_idx)
|
||||
pending = [
|
||||
item
|
||||
for item in plans
|
||||
if records.get(item[2]) not in ("done", "blocked")
|
||||
]
|
||||
if not pending:
|
||||
return 2, "ERROR: no pending plans"
|
||||
|
||||
for plan_key, status, _, _ in entries:
|
||||
if status == "pending":
|
||||
return 0, (plans_dir / plan_key).as_posix()
|
||||
pending.sort(key=lambda item: (item[0], item[2]))
|
||||
return 0, pending[-1][2]
|
||||
|
||||
return 2, "ERROR: no pending plans"
|
||||
|
||||
def ensure_plan_section(text: str) -> str:
|
||||
if PLAN_SECTION_HEADER in text:
|
||||
return text
|
||||
suffix = text
|
||||
if suffix and not suffix.endswith("\n"):
|
||||
suffix += "\n"
|
||||
if suffix:
|
||||
suffix += "\n"
|
||||
suffix += PLAN_SECTION_HEADER + "\n"
|
||||
return suffix
|
||||
|
||||
|
||||
def normalize_note(note: str) -> str:
|
||||
cleaned = note.replace("\n", " ").replace("|", " ").strip()
|
||||
return cleaned
|
||||
|
||||
|
||||
def record_status(plan: str, status: str, progress_path: Path, note: Optional[str]) -> tuple[int, str]:
|
||||
|
|
@ -170,38 +147,24 @@ def record_status(plan: str, status: str, progress_path: Path, note: Optional[st
|
|||
|
||||
progress_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
if progress_path.exists():
|
||||
lines = progress_path.read_text(encoding="utf-8").splitlines()
|
||||
text = progress_path.read_text(encoding="utf-8")
|
||||
else:
|
||||
lines = []
|
||||
text = "# 开发进度追踪\n"
|
||||
|
||||
plan_key = normalize_plan_key(plan)
|
||||
block = find_block(lines)
|
||||
if not block:
|
||||
lines = render_progress_lines([plan_key])
|
||||
block = find_block(lines)
|
||||
if not block:
|
||||
return 2, "ERROR: failed to create plan status block"
|
||||
text = ensure_plan_section(text)
|
||||
if not text.endswith("\n"):
|
||||
text += "\n"
|
||||
|
||||
start_idx, end_idx = block
|
||||
entries = parse_entries(lines, start_idx, end_idx)
|
||||
|
||||
rendered_note = None
|
||||
if status == "blocked" and note:
|
||||
rendered_note = normalize_note(note)
|
||||
|
||||
updated_line = render_plan_line(plan_key, status, rendered_note)
|
||||
updated = False
|
||||
for entry_plan, _, _, idx in entries:
|
||||
if entry_plan == plan_key:
|
||||
lines[idx] = updated_line
|
||||
updated = True
|
||||
break
|
||||
|
||||
if not updated:
|
||||
lines[end_idx:end_idx] = [updated_line]
|
||||
|
||||
progress_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
|
||||
return 0, updated_line
|
||||
date_value = datetime.now().strftime("%Y-%m-%d")
|
||||
plan_path = Path(plan).as_posix()
|
||||
line = f"{PLAN_PREFIX} {plan_path} | status={status} | date={date_value}"
|
||||
if note:
|
||||
cleaned = normalize_note(note)
|
||||
if cleaned:
|
||||
line += f" | note={cleaned}"
|
||||
text += line + "\n"
|
||||
progress_path.write_text(text, encoding="utf-8")
|
||||
return 0, line
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
|
|
@ -259,4 +222,4 @@ def main(argv: list[str]) -> int:
|
|||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main(sys.argv[1:]))
|
||||
sys.exit(main(sys.argv[1:]))
|
||||
|
|
|
|||
|
|
@ -29,8 +29,8 @@
|
|||
### 工作流程
|
||||
|
||||
- [docs/prompts/coding/clarify.md](docs/prompts/coding/clarify.md) - 需求澄清
|
||||
- [docs/prompts/coding/review.md](docs/prompts/coding/review.md) - 复盘总结
|
||||
- [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md) - 工作模式参考
|
||||
- [docs/prompts/coding/verify.md](docs/prompts/coding/verify.md) - 验证检查
|
||||
- [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md) - AI 行为规范
|
||||
<!-- playbook:templates:end -->
|
||||
|
||||
<!-- playbook:framework:end -->
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# AGENT_RULES
|
||||
|
||||
目的：为本仓库提供稳定的执行流程与行为规范。
|
||||
目的：为本仓库提供稳定的执行流程。
|
||||
|
||||
## 优先级
|
||||
|
||||
|
|
@ -14,35 +14,6 @@
|
|||
- 不得在代码/日志/注释中写入明文密钥、密码、Token
|
||||
- 修改鉴权/权限逻辑必须说明动机与风险
|
||||
- 不确定是否敏感时按敏感信息处理
|
||||
- 执行修改文件系统的命令前，必须解释目的和潜在影响
|
||||
|
||||
## 行为准则
|
||||
|
||||
### 项目适应
|
||||
|
||||
- **模仿项目风格**：优先分析周围代码和配置，遵循现有约定
|
||||
- **不假设可用性**：不假设库或框架可用，先验证再使用
|
||||
- **完整完成请求**：不遗漏用户要求的任何部分
|
||||
|
||||
### 技术态度
|
||||
|
||||
- **准确性优先**：技术准确性优先于迎合用户
|
||||
- **诚实纠正**：发现用户理解有误时，礼貌纠正
|
||||
- **先查后答**：不确定时先调查再回答
|
||||
|
||||
### 避免过度工程
|
||||
|
||||
- **只做要求的**：不主动添加未要求的功能或重构
|
||||
- **不过度抽象**：不为一次性操作创建工具函数
|
||||
- **不为未来设计**：不为假设的未来需求设计
|
||||
|
||||
## 沟通原则
|
||||
|
||||
- **简洁直接**：专业、直接、简洁，避免对话填充词
|
||||
- **拒绝时提供替代**：无法满足请求时，简洁说明并提供替代方案
|
||||
- **不给时间估算**：专注任务本身，让用户自己判断时间
|
||||
- **代码块标注语言**：输出代码时标注语言类型
|
||||
- **不使用 emoji**：除非用户明确要求
|
||||
|
||||
## 上下文加载（每次会话开始）
|
||||
|
||||
|
|
@ -59,47 +30,23 @@
|
|||
|
||||
**目的**：让 AI 快速理解项目全貌，避免重复解释。
|
||||
|
||||
## 规划与执行分工
|
||||
|
||||
| 阶段 | 工具 | 产出 | 留痕 |
|
||||
| ------------ | ---------------------- | ----------------- | -------------------- |
|
||||
| 头脑风暴 | `$brainstorming` skill | 设计思路 | 无 |
|
||||
| 生成计划 | `$writing-plans` skill | `docs/plans/*.md` | 无 |
|
||||
| **执行计划** | **主循环** | 代码/配置变更 | **plan_progress.py** |
|
||||
|
||||
> **重要**：第三方 skills 不记录操作状态，执行必须通过主循环完成。
|
||||
|
||||
## 主循环
|
||||
|
||||
**触发词**：
|
||||
|
||||
| 触发词 | 模式 | 说明 |
|
||||
| --------------------------------------- | ---------- | ---------------------- |
|
||||
| `执行主循环`、`继续执行`、`下一个 Plan` | 常规模式 | 遇确认场景可询问用户 |
|
||||
| `自动执行所有 Plan` | 无交互模式 | 不询问，按规则自动处理 |
|
||||
|
||||
0. 选择 Plan：
|
||||
- 运行 `python {{PLAYBOOK_SCRIPTS}}/plan_progress.py select -plans docs/plans -progress memory-bank/progress.md`
|
||||
- 如无可执行 Plan，跳到步骤 4
|
||||
1. 阅读 Plan：
|
||||
- 如无可执行 Plan，说明情况并询问用户下一步（新增 Plan/切换任务/结束）
|
||||
1. 标记开始：
|
||||
- `python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status in-progress -progress memory-bank/progress.md`
|
||||
2. 阅读 Plan：
|
||||
- 理解目标、子任务与验证标准
|
||||
2. 逐步执行：
|
||||
3. 逐步执行：
|
||||
- 按顺序执行子任务
|
||||
- 每步完成后进行必要验证（测试/日志/diff）
|
||||
- 遇到歧义/风险/决策点：
|
||||
- 常规模式：记录到回复中，可询问用户
|
||||
- 无交互模式：按「需要确认的场景」规则自动处理
|
||||
- 遇到阻塞：记录原因，跳到步骤 3 标记 blocked
|
||||
- **安全红线阻塞**（发现明文密钥等）：立即停止，不继续后续 Plan
|
||||
3. 记录结果：
|
||||
- 遇到阻塞立即记录并停止
|
||||
4. 记录结果（写入 `memory-bank/progress.md`）：
|
||||
- 完成：`python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status done -progress memory-bank/progress.md`
|
||||
- 阻塞：`python {{PLAYBOOK_SCRIPTS}}/plan_progress.py record -plan <plan> -status blocked -progress memory-bank/progress.md -note <原因>`
|
||||
- 回到步骤 0 继续下一个 Plan
|
||||
4. 汇总报告（所有 Plan 处理完毕后）：
|
||||
- 列出已完成的 Plan
|
||||
- 列出阻塞的 Plan 及原因
|
||||
- 列出待确认的歧义/风险/决策点
|
||||
- 如需记录重要决策，写入 `memory-bank/decisions.md`
|
||||
5. 如存在歧义/风险/决策点，在回复中明确提出，并视需要记录到 `memory-bank/decisions.md`
|
||||
|
||||
## Plan 规则
|
||||
|
||||
|
|
@ -117,37 +64,20 @@
|
|||
|
||||
## 执行约束
|
||||
|
||||
### 代码修改
|
||||
### 代码修改约束
|
||||
|
||||
- **必须先读文件再修改**：不读文件就提议修改是禁止的
|
||||
- **必须运行测试验证**：相关测试必须通过
|
||||
- **遵循换行规则**：遵循 `.gitattributes` 规则
|
||||
- **命名一致性**：遵循项目现有的命名风格
|
||||
- **最小改动原则**：只修改必要的部分，不顺手重构
|
||||
|
||||
### 决策记录
|
||||
### 决策记录约束
|
||||
|
||||
- **重要决策**：记录到 `memory-bank/decisions.md`（ADR 格式）
|
||||
- **待确认事项**：在回复中列出并等待确认
|
||||
- **进度留痕**：通过 `{{PLAYBOOK_SCRIPTS}}/plan_progress.py` 维护 `memory-bank/progress.md` 的 Plan 状态块（唯一权威）
|
||||
|
||||
### Git 操作
|
||||
|
||||
- **不使用 --amend**：除非用户明确要求，总是创建新提交
|
||||
- **不使用 --force**：特别是推送到 main/master，如用户要求必须警告风险
|
||||
- **不跳过 hooks**：不使用 `--no-verify`
|
||||
|
||||
## 工具使用
|
||||
|
||||
- **并行执行**：独立的工具调用尽可能并行执行
|
||||
- **遵循 schema**：严格遵循工具参数定义
|
||||
- **避免循环**：避免重复调用同一工具获取相同信息
|
||||
- **优先专用工具**：文件操作用 Read/Edit/Write，搜索用 Grep/Glob
|
||||
- **进度留痕**：通过 `{{PLAYBOOK_SCRIPTS}}/plan_progress.py` 写入 `memory-bank/progress.md`，该文件为 Plan 状态唯一权威
|
||||
|
||||
## 需要确认的场景
|
||||
|
||||
**常规模式**（可交互）：
|
||||
|
||||
- 需求不明确或存在多种可行方案
|
||||
- 需要行为/兼容性取舍
|
||||
- 风险或约束冲突
|
||||
|
|
@ -155,21 +85,6 @@
|
|||
- **性能权衡**：需要在性能和可维护性之间选择
|
||||
- **兼容性问题**：可能破坏现有用户代码
|
||||
|
||||
**无交互模式**（自动处理）：
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
| -------------------------- | ---------------------------------- |
|
||||
| 安全红线 | 立即停止，不继续后续 Plan |
|
||||
| 架构变更/兼容性/破坏性修改 | 标记 blocked，跳到下一个 Plan |
|
||||
| 多种可行方案 | 选择最保守方案，记录选择理由到报告 |
|
||||
| 歧义/风险/决策点 | 记录到报告，继续执行 |
|
||||
|
||||
**可以不确认**（两种模式通用）：
|
||||
|
||||
- 明显的 bug 修复
|
||||
- 符合现有模式的小改动
|
||||
- 测试用例补充
|
||||
|
||||
## 验证清单
|
||||
|
||||
每个 Plan 完成后，必须验证：
|
||||
|
|
@ -178,7 +93,7 @@
|
|||
- [ ] 相关测试通过（如有测试且未被豁免）
|
||||
- [ ] 换行符正确
|
||||
- [ ] 无语法错误
|
||||
- [ ] 已通过 `plan_progress.py` 记录 Plan 状态
|
||||
- [ ] 已更新 `memory-bank/progress.md`
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,43 +1,109 @@
|
|||
# 架构设计
|
||||
|
||||
<!--
|
||||
填写指南：
|
||||
- 【必填】：项目启动前必须填写
|
||||
- 【可选】：按需填写，可随项目发展补充
|
||||
- 小项目可只填核心模块，架构图可后补
|
||||
-->
|
||||
|
||||
## 整体架构
|
||||
|
||||
<!-- 【可选】项目成熟后补充 -->
|
||||
|
||||
```txt
|
||||
{{ARCHITECTURE_DIAGRAM}}
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ {{LAYER_1}} │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ {{LAYER_2}} │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ {{LAYER_3}} │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 核心模块
|
||||
|
||||
<!-- 【必填】至少列出主要模块 -->
|
||||
|
||||
### {{MODULE_1}}
|
||||
### 1. {{MODULE_1}}
|
||||
|
||||
**职责**：{{MODULE_1_DESC}}
|
||||
|
||||
**主要组件**：
|
||||
|
||||
- {{COMPONENT_1}}
|
||||
- {{COMPONENT_2}}
|
||||
|
||||
**核心方法**：
|
||||
|
||||
- {{METHOD_1}}
|
||||
- {{METHOD_2}}
|
||||
|
||||
---
|
||||
|
||||
### 2. {{MODULE_2}}
|
||||
|
||||
**职责**：{{MODULE_2_DESC}}
|
||||
|
||||
**主要组件**：
|
||||
|
||||
- {{COMPONENT_3}}
|
||||
- {{COMPONENT_4}}
|
||||
|
||||
---
|
||||
|
||||
### 3. {{MODULE_3}}
|
||||
|
||||
**职责**：{{MODULE_3_DESC}}
|
||||
|
||||
---
|
||||
|
||||
## 设计模式
|
||||
|
||||
### {{PATTERN_1}}
|
||||
|
||||
**应用**：{{PATTERN_1_USAGE}}
|
||||
|
||||
**目的**：{{PATTERN_1_PURPOSE}}
|
||||
|
||||
**优点**：
|
||||
|
||||
- {{PATTERN_1_ADVANTAGE_1}}
|
||||
- {{PATTERN_1_ADVANTAGE_2}}
|
||||
|
||||
### {{PATTERN_2}}
|
||||
|
||||
**应用**：{{PATTERN_2_USAGE}}
|
||||
|
||||
**目的**：{{PATTERN_2_PURPOSE}}
|
||||
|
||||
---
|
||||
|
||||
## 关键约束
|
||||
|
||||
<!-- 【可选】 -->
|
||||
### 1. {{CONSTRAINT_CATEGORY_1}}
|
||||
|
||||
- {{CONSTRAINT_1}}
|
||||
- {{CONSTRAINT_2}}
|
||||
|
||||
### 2. {{CONSTRAINT_CATEGORY_2}}
|
||||
|
||||
- {{CONSTRAINT_3}}
|
||||
- {{CONSTRAINT_4}}
|
||||
|
||||
---
|
||||
|
||||
## 扩展点
|
||||
|
||||
<!-- 【可选】大项目建议填写 -->
|
||||
|
||||
### {{EXTENSION_1}}
|
||||
### 1. {{EXTENSION_1}}
|
||||
|
||||
**步骤**：
|
||||
|
||||
1. {{STEP_1}}
|
||||
2. {{STEP_2}}
|
||||
3. {{STEP_3}}
|
||||
|
||||
### 2. {{EXTENSION_2}}
|
||||
|
||||
**步骤**：
|
||||
|
||||
1. {{STEP_4}}
|
||||
2. {{STEP_5}}
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,50 @@
|
|||
# 架构决策记录
|
||||
|
||||
<!--
|
||||
填写指南：
|
||||
- 本文件记录重要架构决策，使用 ADR 格式
|
||||
- 初始可为空，遇到重要决策时由 AI 或人工添加
|
||||
- 每个决策使用下方模板
|
||||
-->
|
||||
本文档记录项目中的重要架构决策，使用 ADR (Architecture Decision Record) 格式。
|
||||
|
||||
---
|
||||
|
||||
## ADR-001: {{DECISION_1_TITLE}}
|
||||
|
||||
**日期**: {{DATE}}
|
||||
**状态**: 已采纳
|
||||
|
||||
### 决策
|
||||
|
||||
{{DECISION_1_CONTENT}}
|
||||
|
||||
### 理由
|
||||
|
||||
{{DECISION_1_REASON}}
|
||||
|
||||
### 影响
|
||||
|
||||
{{DECISION_1_IMPACT}}
|
||||
|
||||
### 实施细节
|
||||
|
||||
{{DECISION_1_IMPLEMENTATION}}
|
||||
|
||||
---
|
||||
|
||||
## ADR-002: {{DECISION_2_TITLE}}
|
||||
|
||||
**日期**: {{DATE}}
|
||||
**状态**: 已采纳
|
||||
|
||||
### 决策
|
||||
|
||||
{{DECISION_2_CONTENT}}
|
||||
|
||||
### 理由
|
||||
|
||||
{{DECISION_2_REASON}}
|
||||
|
||||
### 影响
|
||||
|
||||
{{DECISION_2_IMPACT}}
|
||||
|
||||
---
|
||||
|
||||
## ADR 模板
|
||||
|
||||
|
|
@ -26,6 +65,10 @@
|
|||
### 影响
|
||||
|
||||
对项目的影响
|
||||
|
||||
### 替代方案（可选）
|
||||
|
||||
考虑过但未采纳的方案
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,4 +1,31 @@
|
|||
# Plan 状态
|
||||
# 开发进度追踪
|
||||
|
||||
<!-- plan-status:start -->
|
||||
<!-- plan-status:end -->
|
||||
## 已知问题
|
||||
|
||||
<!-- 记录已知但暂不解决的问题 -->
|
||||
|
||||
#### {{ISSUE_CATEGORY_1}}
|
||||
|
||||
- {{ISSUE_1}}
|
||||
- **临时方案**：{{WORKAROUND_1}}
|
||||
- **长期方案**：{{SOLUTION_1}}
|
||||
|
||||
## 里程碑
|
||||
|
||||
#### M1: {{MILESTONE_1}}（目标：{{TARGET_DATE_1}}）
|
||||
|
||||
- [ ] {{MILESTONE_1_TASK_1}}
|
||||
- [ ] {{MILESTONE_1_TASK_2}}
|
||||
|
||||
#### M2: {{MILESTONE_2}}（目标：{{TARGET_DATE_2}}）
|
||||
|
||||
- [ ] {{MILESTONE_2_TASK_1}}
|
||||
- [ ] {{MILESTONE_2_TASK_2}}
|
||||
|
||||
## Plan 状态记录
|
||||
|
||||
<!-- 由 plan_progress.py 自动管理，请勿手动编辑此节内容 -->
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
|
|
|
|||
|
|
@ -1,47 +1,65 @@
|
|||
# {{PROJECT_NAME}} 项目简介
|
||||
|
||||
<!--
|
||||
填写指南：
|
||||
- 【必填】：项目启动前必须填写
|
||||
- 【可选】：按需填写，可随项目发展补充
|
||||
- 未填写的占位符保持原样或删除整行
|
||||
-->
|
||||
|
||||
## 项目定位
|
||||
|
||||
<!-- 【必填】 -->
|
||||
|
||||
**核心目标**：{{PROJECT_GOAL}}
|
||||
|
||||
**一句话描述**：{{PROJECT_DESCRIPTION}}
|
||||
|
||||
## 项目边界
|
||||
## 为什么做这个项目？
|
||||
|
||||
<!-- 【必填】至少填写"做什么" -->
|
||||
### 问题
|
||||
|
||||
- {{PROBLEM_1}}
|
||||
- {{PROBLEM_2}}
|
||||
- {{PROBLEM_3}}
|
||||
|
||||
### 解决方案
|
||||
|
||||
- {{SOLUTION_1}}
|
||||
- {{SOLUTION_2}}
|
||||
- {{SOLUTION_3}}
|
||||
|
||||
## 项目边界
|
||||
|
||||
### 做什么
|
||||
|
||||
- {{DO_1}}
|
||||
- {{DO_2}}
|
||||
- {{DO_3}}
|
||||
|
||||
### 不做什么
|
||||
|
||||
<!-- 【可选】 -->
|
||||
|
||||
- {{DONT_1}}
|
||||
- {{DONT_2}}
|
||||
- {{DONT_3}}
|
||||
|
||||
### 约束条件
|
||||
|
||||
<!-- 【可选】 -->
|
||||
|
||||
- {{CONSTRAINT_1}}
|
||||
- {{CONSTRAINT_2}}
|
||||
- {{CONSTRAINT_3}}
|
||||
|
||||
## 核心概念
|
||||
|
||||
<!-- 【可选】项目特有的术语或概念 -->
|
||||
<!-- 根据项目需要填写核心概念 -->
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **主语言**：{{MAIN_LANGUAGE}}
|
||||
- **外部依赖**：{{DEPENDENCIES}}
|
||||
- **测试环境**：{{TEST_ENV}}
|
||||
|
||||
## 参考资料
|
||||
|
||||
<!-- 【可选】 -->
|
||||
- {{REFERENCE_1}}
|
||||
- {{REFERENCE_2}}
|
||||
|
||||
## 当前状态
|
||||
|
||||
- {{STATUS_1}}
|
||||
- {{STATUS_2}}
|
||||
- {{STATUS_3}}
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,63 +1,117 @@
|
|||
# 技术栈与工具链
|
||||
|
||||
<!--
|
||||
填写指南：
|
||||
- 【必填】：项目启动前必须填写
|
||||
- 【可选】：按需填写，可随项目发展补充
|
||||
- 未填写的占位符保持原样或删除整行
|
||||
-->
|
||||
|
||||
## 核心技术
|
||||
|
||||
<!-- 【必填】 -->
|
||||
### 主语言：{{MAIN_LANGUAGE}}
|
||||
|
||||
**主语言**：{{MAIN_LANGUAGE}}
|
||||
**文件类型**：
|
||||
|
||||
**文件类型**：{{FILE_TYPES}}
|
||||
- {{FILE_TYPE_1}}
|
||||
- {{FILE_TYPE_2}}
|
||||
|
||||
**特点**：
|
||||
|
||||
- {{FEATURE_1}}
|
||||
- {{FEATURE_2}}
|
||||
- {{FEATURE_3}}
|
||||
|
||||
**运行方式**：
|
||||
|
||||
- {{RUN_METHOD_1}}
|
||||
- {{RUN_METHOD_2}}
|
||||
|
||||
## 项目结构
|
||||
|
||||
<!-- 【必填】 -->
|
||||
|
||||
```text
|
||||
{{PROJECT_NAME}}/
|
||||
├── {{DIR_1}}/ # {{DIR_1_DESC}}
|
||||
├── {{DIR_2}}/ # {{DIR_2_DESC}}
|
||||
├── {{DIR_3}}/ # {{DIR_3_DESC}}
|
||||
└── memory-bank/ # 项目上下文
|
||||
```
|
||||
|
||||
## 开发环境
|
||||
|
||||
<!-- 【必填】至少填写运行测试命令 -->
|
||||
### {{ENV_1}}
|
||||
|
||||
**必需工具**：
|
||||
|
||||
- {{TOOL_1}}
|
||||
- {{TOOL_2}}
|
||||
|
||||
**运行测试**：
|
||||
|
||||
```bash
|
||||
{{TEST_CMD}}
|
||||
{{TEST_CMD_1}}
|
||||
```
|
||||
|
||||
## 依赖管理
|
||||
### {{ENV_2}}（如有）
|
||||
|
||||
<!-- 【可选】 -->
|
||||
**必需工具**：
|
||||
|
||||
**外部依赖**：
|
||||
- {{TOOL_3}}
|
||||
- {{TOOL_4}}
|
||||
|
||||
- {{EXTERNAL_DEP_1}}
|
||||
## 版本控制
|
||||
|
||||
### Git 配置
|
||||
|
||||
**换行规则**（`.gitattributes`）：
|
||||
|
||||
- 遵循 `.gitattributes` 文件定义
|
||||
|
||||
**忽略规则**（`.gitignore`）：
|
||||
|
||||
- 以 `.gitignore` 实际内容为准
|
||||
|
||||
### 分支策略
|
||||
|
||||
- `master`/`main`：主分支（稳定版本）
|
||||
- 功能分支：按需创建
|
||||
|
||||
## 测试策略
|
||||
|
||||
<!-- 【可选】大项目建议填写 -->
|
||||
|
||||
**测试类型**：
|
||||
### 测试类型
|
||||
|
||||
- {{TEST_TYPE_1}}
|
||||
- {{TEST_TYPE_2}}
|
||||
|
||||
**验证标准**：
|
||||
### 验证标准
|
||||
|
||||
- {{PASS_CONDITION_1}}
|
||||
**测试通过条件**：
|
||||
|
||||
1. {{PASS_CONDITION_1}}
|
||||
2. {{PASS_CONDITION_2}}
|
||||
3. {{PASS_CONDITION_3}}
|
||||
|
||||
**常见失败原因**：
|
||||
|
||||
- {{FAIL_REASON_1}}
|
||||
- {{FAIL_REASON_2}}
|
||||
|
||||
## 依赖管理
|
||||
|
||||
### 外部依赖
|
||||
|
||||
- {{EXTERNAL_DEP_1}}
|
||||
- {{EXTERNAL_DEP_2}}
|
||||
|
||||
### 内部依赖
|
||||
|
||||
- {{INTERNAL_DEP_1}}
|
||||
- {{INTERNAL_DEP_2}}
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 当前瓶颈
|
||||
|
||||
- {{BOTTLENECK_1}}
|
||||
- {{BOTTLENECK_2}}
|
||||
|
||||
### 优化方向
|
||||
|
||||
- {{OPTIMIZATION_1}}
|
||||
- {{OPTIMIZATION_2}}
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,47 +1,41 @@
|
|||
# 提示词库
|
||||
|
||||
本目录包含 AI 代理的工作流程参考模板。
|
||||
本目录包含 AI 代理的工作流程模板和参考文档。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```text
|
||||
prompts/
|
||||
├── README.md # 本文件
|
||||
├── system/
|
||||
│ └── agent-behavior.md # 工作模式参考
|
||||
├── coding/
|
||||
│ ├── clarify.md # 需求澄清模板
|
||||
│ └── review.md # 复盘总结模板
|
||||
└── meta/
|
||||
└── prompt-generator.md # 元提示词生成器
|
||||
├── README.md # 本文件
|
||||
├── system/ # 系统级规范
|
||||
│ └── agent-behavior.md
|
||||
├── coding/ # 编码流程
|
||||
│ ├── clarify.md # 需求澄清模板
|
||||
│ └── verify.md # 验证检查清单
|
||||
└── user/ # 用户快捷命令
|
||||
└── quick-test.md # 快速测试命令
|
||||
```
|
||||
|
||||
## 使用方式
|
||||
|
||||
| 模板 | 触发场景 |
|
||||
| ----------------------- | ------------------------------ |
|
||||
| **agent-behavior.md** | 切换工作模式（探索/开发/调试） |
|
||||
| **clarify.md** | 需求不明确时澄清 |
|
||||
| **review.md** | Plan 完成后复盘总结 |
|
||||
| **prompt-generator.md** | 创建新的专用提示词 |
|
||||
### AI 代理
|
||||
|
||||
## 工作流程
|
||||
- 新会话时读取 `system/agent-behavior.md`
|
||||
- 需要澄清需求时参考 `coding/clarify.md`
|
||||
- 完成任务前检查 `coding/verify.md`
|
||||
|
||||
```
|
||||
需求不清 → clarify.md
|
||||
↓
|
||||
头脑风暴 → $brainstorming skill
|
||||
↓
|
||||
生成计划 → $writing-plans skill → docs/plans/*.md
|
||||
↓
|
||||
执行计划 → AGENT_RULES 主循环（留痕）
|
||||
↓
|
||||
完成复盘 → review.md
|
||||
↓
|
||||
沉淀提示词 → prompt-generator.md（可选）
|
||||
```
|
||||
### 用户
|
||||
|
||||
> **核心规则在 `AGENT_RULES.md`**，第三方 skills 负责规划，主循环负责执行和留痕。
|
||||
- 使用 `user/quick-test.md` 中的命令快速执行测试
|
||||
|
||||
## 文档说明
|
||||
|
||||
| 文件 | 用途 |
|
||||
| -------------------------- | ------------------------------- |
|
||||
| `system/agent-behavior.md` | AI 行为规范、工作模式、禁止行为 |
|
||||
| `coding/clarify.md` | 需求澄清步骤和问题模板 |
|
||||
| `coding/verify.md` | 代码、测试、文档验证清单 |
|
||||
| `user/quick-test.md` | 常用测试命令参考 |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,5 @@
|
|||
# 需求澄清模板
|
||||
|
||||
<!--
|
||||
按需使用：当需求不明确或存在歧义时参考本模板。
|
||||
Vibe-coding 场景下可跳过，直接开始实现。
|
||||
-->
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 需求描述不明确
|
||||
|
|
@ -15,37 +10,119 @@ Vibe-coding 场景下可跳过，直接开始实现。
|
|||
|
||||
## 澄清步骤
|
||||
|
||||
### 1. 复述需求
|
||||
### 1. 理解当前需求
|
||||
|
||||
**复述需求**：
|
||||
|
||||
```text
|
||||
我理解你的需求是：[用自己的话复述]
|
||||
```
|
||||
|
||||
### 2. 识别歧义
|
||||
**识别歧义点**：
|
||||
|
||||
- 歧义 1：[描述不明确的地方]
|
||||
- 歧义 2：[可能有多种理解的地方]
|
||||
|
||||
### 3. 提出问题
|
||||
---
|
||||
|
||||
### 2. 提出澄清问题
|
||||
|
||||
**问题模板**：
|
||||
|
||||
> 只问阻塞问题，最多 1–2 个；优先给出选项让用户选择。
|
||||
|
||||
- 这个功能是否包括 [场景 A]？
|
||||
- 当 [条件 X] 时，应该 [行为 Y] 还是 [行为 Z]？
|
||||
#### 功能范围
|
||||
|
||||
### 4. 提供选项
|
||||
- 这个功能是否包括 [场景 A]？
|
||||
- 是否需要支持 [边界情况 B]？
|
||||
- 优先级如何？必须有 vs 可选
|
||||
|
||||
#### 行为细节
|
||||
|
||||
- 当 [条件 X] 时，应该 [行为 Y] 还是 [行为 Z]？
|
||||
- 如果 [异常情况]，如何处理？
|
||||
- 是否需要与 [现有功能] 保持一致？
|
||||
|
||||
#### 技术约束
|
||||
|
||||
- 是否有性能要求？
|
||||
- 是否有兼容性要求？
|
||||
- 是否有安全要求？
|
||||
|
||||
---
|
||||
|
||||
### 3. 提供选项
|
||||
|
||||
**选项格式**：
|
||||
|
||||
**选项 A**：[方案描述]
|
||||
|
||||
- 优点：...
|
||||
- 缺点：...
|
||||
- 优点：[列出优点]
|
||||
- 缺点：[列出缺点]
|
||||
- 适用场景：[什么情况下选这个]
|
||||
|
||||
**选项 B**：[方案描述]
|
||||
|
||||
- 优点：...
|
||||
- 缺点：...
|
||||
- 优点：[列出优点]
|
||||
- 缺点：[列出缺点]
|
||||
- 适用场景：[什么情况下选这个]
|
||||
|
||||
**推荐**：[推荐哪个，为什么]
|
||||
**推荐**：[推荐哪个选项，为什么]
|
||||
|
||||
---
|
||||
|
||||
### 4. 确认理解
|
||||
|
||||
**确认清单**：
|
||||
|
||||
- [ ] 功能范围明确
|
||||
- [ ] 行为细节清晰
|
||||
- [ ] 技术约束已知
|
||||
- [ ] 优先级确定
|
||||
- [ ] 验收标准明确
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 需求
|
||||
|
||||
```text
|
||||
实现 XXX 功能
|
||||
```
|
||||
|
||||
### 澄清过程
|
||||
|
||||
**复述需求**：
|
||||
|
||||
```text
|
||||
我理解你的需求是：为 YYY 添加 XXX 功能，
|
||||
用于 ZZZ。
|
||||
```
|
||||
|
||||
**识别歧义点**：
|
||||
|
||||
- 歧义 1：XXX 是只读还是可写？
|
||||
- 歧义 2：是否需要支持所有场景？
|
||||
|
||||
**澄清问题**：
|
||||
|
||||
- 是否需要支持 [场景 A]？
|
||||
- 当 [条件 X] 时，应该如何处理？
|
||||
|
||||
**提供选项**：
|
||||
|
||||
**选项 A**：完整实现
|
||||
|
||||
- 优点：功能完整
|
||||
- 缺点：开发周期长
|
||||
|
||||
**选项 B**：核心功能
|
||||
|
||||
- 优点：快速交付
|
||||
- 缺点：功能有限
|
||||
|
||||
**推荐**：选项 A，因为 [原因]。
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,66 +0,0 @@
|
|||
# 复盘模板
|
||||
|
||||
<!--
|
||||
用途：Plan 或阶段完成后的回顾总结
|
||||
触发：主循环汇总报告时、阶段性工作完成时
|
||||
-->
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 一批 Plan 执行完毕后
|
||||
- 阶段性工作告一段落
|
||||
- 遇到重大阻塞需要总结
|
||||
|
||||
---
|
||||
|
||||
## 复盘格式
|
||||
|
||||
```markdown
|
||||
# 复盘: [日期/阶段名称]
|
||||
|
||||
## 完成情况
|
||||
|
||||
### 已完成
|
||||
- [x] Plan 1: 简述
|
||||
- [x] Plan 2: 简述
|
||||
|
||||
### 阻塞
|
||||
- [ ] Plan 3: 阻塞原因
|
||||
|
||||
### 跳过
|
||||
- [ ] Plan 4: 跳过原因
|
||||
|
||||
## 关键发现
|
||||
|
||||
### 做得好的
|
||||
- 发现1
|
||||
- 发现2
|
||||
|
||||
### 待改进
|
||||
- 问题1 → 建议改进方式
|
||||
- 问题2 → 建议改进方式
|
||||
|
||||
## 决策记录
|
||||
|
||||
| 决策 | 理由 | 影响 |
|
||||
|------|------|------|
|
||||
| 决策1 | 为什么 | 影响范围 |
|
||||
|
||||
## 下一步
|
||||
|
||||
- [ ] 待处理事项1
|
||||
- [ ] 待处理事项2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 复盘原则
|
||||
|
||||
- **客观记录**：如实记录完成/阻塞/跳过
|
||||
- **提取经验**：总结做得好的和待改进的
|
||||
- **决策留痕**：重要决策记录到 decisions.md
|
||||
- **明确下一步**：列出后续待处理事项
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
|
|
@ -0,0 +1,93 @@
|
|||
# 验证检查清单
|
||||
|
||||
## 代码修改验证
|
||||
|
||||
### 语法检查
|
||||
|
||||
- [ ] 代码可正常运行（无语法错误）
|
||||
- [ ] 无未定义的变量或函数
|
||||
- [ ] 依赖引用正确
|
||||
|
||||
### 风格检查
|
||||
|
||||
- [ ] 命名符合规范
|
||||
- [ ] 缩进正确
|
||||
- [ ] 换行符正确（遵循 .gitattributes）
|
||||
- [ ] 无冗余注释
|
||||
|
||||
---
|
||||
|
||||
## 测试验证
|
||||
|
||||
### 单元测试
|
||||
|
||||
- [ ] 相关测试脚本存在
|
||||
- [ ] 测试可正常运行
|
||||
- [ ] 测试通过（无失败）
|
||||
|
||||
### 回归测试
|
||||
|
||||
- [ ] 现有测试仍然通过
|
||||
- [ ] 未破坏其他功能
|
||||
|
||||
---
|
||||
|
||||
## 文档验证
|
||||
|
||||
### 代码文档
|
||||
|
||||
- [ ] 复杂逻辑有注释说明
|
||||
- [ ] 公开 API 有使用示例（如需）
|
||||
|
||||
### 项目文档
|
||||
|
||||
- [ ] `memory-bank/progress.md` 已更新
|
||||
- [ ] 重要决策记录到 `memory-bank/decisions.md`
|
||||
|
||||
---
|
||||
|
||||
## Git 验证
|
||||
|
||||
### 提交前检查
|
||||
|
||||
- [ ] 只包含相关修改（无无关文件）
|
||||
- [ ] 提交信息清晰
|
||||
- [ ] 无临时文件或调试代码
|
||||
|
||||
### 分支检查
|
||||
|
||||
- [ ] 在正确的分支上工作
|
||||
|
||||
---
|
||||
|
||||
## 性能验证（如果涉及）
|
||||
|
||||
### 性能测试
|
||||
|
||||
- [ ] 处理时间可接受
|
||||
- [ ] 内存使用正常
|
||||
- [ ] 无明显性能退化
|
||||
|
||||
---
|
||||
|
||||
## 安全验证（如果涉及）
|
||||
|
||||
### 安全检查
|
||||
|
||||
- [ ] 无注入风险
|
||||
- [ ] 敏感信息已脱敏
|
||||
|
||||
---
|
||||
|
||||
## 快速检查清单（最小集）
|
||||
|
||||
**每次修改必须检查**：
|
||||
|
||||
- [ ] 代码可运行（无语法错误）
|
||||
- [ ] 相关测试通过
|
||||
- [ ] 换行符正确
|
||||
- [ ] `memory-bank/progress.md` 已更新
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
|
|
@ -1,126 +0,0 @@
|
|||
# 提示词生成器（元提示词）
|
||||
|
||||
<!--
|
||||
用途：根据场景自动生成专用提示词
|
||||
原理：α-prompts（生成）+ Ω-prompts（优化）递归循环
|
||||
-->
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 需要为新场景创建专用提示词
|
||||
- 现有提示词不满足特定需求
|
||||
- 需要批量生成同类提示词
|
||||
|
||||
---
|
||||
|
||||
## 生成流程（α循环）
|
||||
|
||||
### 1. 分析场景
|
||||
|
||||
```markdown
|
||||
**场景名称**：[名称]
|
||||
**目标用户**：[AI/人类/两者]
|
||||
**触发条件**：[何时使用这个提示词]
|
||||
**预期输出**：[使用后应该产出什么]
|
||||
```
|
||||
|
||||
### 2. 提取约束
|
||||
|
||||
```markdown
|
||||
**必须做**：
|
||||
- 约束1
|
||||
- 约束2
|
||||
|
||||
**禁止做**：
|
||||
- 禁止1
|
||||
- 禁止2
|
||||
|
||||
**边界条件**：
|
||||
- 边界1
|
||||
- 边界2
|
||||
```
|
||||
|
||||
### 3. 生成草稿
|
||||
|
||||
```markdown
|
||||
# [提示词标题]
|
||||
|
||||
<!--
|
||||
用途：[一句话描述]
|
||||
触发：[触发条件]
|
||||
-->
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 场景1
|
||||
- 场景2
|
||||
|
||||
## [核心内容]
|
||||
|
||||
[根据场景填充]
|
||||
|
||||
## [约束/原则]
|
||||
|
||||
- 约束1
|
||||
- 约束2
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 优化流程（Ω循环）
|
||||
|
||||
### 1. 评估维度
|
||||
|
||||
| 维度 | 问题 |
|
||||
| ---------- | ---------------------- |
|
||||
| **清晰度** | 指令是否明确无歧义？ |
|
||||
| **完整度** | 是否覆盖所有必要场景？ |
|
||||
| **简洁度** | 是否有冗余内容可删除？ |
|
||||
| **可操作** | AI 能否直接执行？ |
|
||||
|
||||
### 2. 迭代优化
|
||||
|
||||
```
|
||||
草稿 → 评估 → 修改 → 再评估 → ... → 定稿
|
||||
```
|
||||
|
||||
### 3. 验证测试
|
||||
|
||||
- 用实际场景测试提示词效果
|
||||
- 收集反馈，持续迭代
|
||||
|
||||
---
|
||||
|
||||
## 提示词模板库
|
||||
|
||||
### 标准结构
|
||||
|
||||
```markdown
|
||||
# [标题]
|
||||
|
||||
<!--
|
||||
用途：
|
||||
触发：
|
||||
-->
|
||||
|
||||
## 何时使用
|
||||
## [核心内容]
|
||||
## [约束/原则]
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
```
|
||||
|
||||
### 命名规范
|
||||
|
||||
- 文件名：`[动词]-[对象].template.md`
|
||||
- 示例：`clarify-requirement.template.md`
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
|
|
@ -1,19 +1,18 @@
|
|||
# 工作模式参考
|
||||
# AI 代理行为规范
|
||||
|
||||
<!--
|
||||
本文件定义三种工作模式，供 AI 根据任务类型选择。
|
||||
核心规则（安全红线、验证清单等）见 AGENT_RULES.md。
|
||||
-->
|
||||
## 工作模式
|
||||
|
||||
## 模式 1: 探索模式（Explore）
|
||||
### 模式 1: 探索模式（Explore）
|
||||
|
||||
**目的**：理解代码库、分析问题、收集信息
|
||||
|
||||
**行为**：
|
||||
**行为规范**：
|
||||
|
||||
- 使用搜索工具探索代码
|
||||
- 输出分析报告和发现
|
||||
- 提出问题和建议
|
||||
- 不修改任何代码
|
||||
- 不运行测试（除非明确要求）
|
||||
|
||||
**适用场景**：
|
||||
|
||||
|
|
@ -23,15 +22,18 @@
|
|||
|
||||
---
|
||||
|
||||
## 模式 2: 开发模式（Develop）
|
||||
### 模式 2: 开发模式（Develop）
|
||||
|
||||
**目的**：实现功能、修复 bug、重构代码
|
||||
|
||||
**行为**：
|
||||
**行为规范**：
|
||||
|
||||
- 先读取相关文件，理解现有逻辑
|
||||
- 进行精确修改
|
||||
- 修改后运行测试验证
|
||||
- 修改后运行对应测试验证
|
||||
- 更新 `memory-bank/progress.md`
|
||||
- 不读文件就提议修改
|
||||
- 不跳过测试直接提交
|
||||
|
||||
**适用场景**：
|
||||
|
||||
|
|
@ -41,15 +43,16 @@
|
|||
|
||||
---
|
||||
|
||||
## 模式 3: 调试模式（Debug）
|
||||
### 模式 3: 调试模式（Debug）
|
||||
|
||||
**目的**：诊断问题、对比差异、验证行为
|
||||
|
||||
**行为**：
|
||||
**行为规范**：
|
||||
|
||||
- 收集相关日志和输出
|
||||
- 分析差异原因
|
||||
- 修复后重新验证
|
||||
- 记录待确认事项并在回复中提出，或直接修复
|
||||
- 重新验证
|
||||
|
||||
**适用场景**：
|
||||
|
||||
|
|
@ -59,4 +62,135 @@
|
|||
|
||||
---
|
||||
|
||||
## 代码风格要求
|
||||
|
||||
### 通用规范
|
||||
|
||||
**命名规范**：
|
||||
|
||||
- 遵循项目现有的命名风格
|
||||
- 保持一致性
|
||||
|
||||
**缩进**：
|
||||
|
||||
- 遵循项目现有的缩进风格
|
||||
|
||||
**换行**：
|
||||
|
||||
- 遵循 `.gitattributes` 规则
|
||||
|
||||
**注释**：
|
||||
|
||||
- 只在逻辑不自明时添加注释
|
||||
- 不添加冗余注释
|
||||
|
||||
---
|
||||
|
||||
## 禁止行为清单
|
||||
|
||||
### 代码修改
|
||||
|
||||
- **不读文件就提议修改**
|
||||
|
||||
- 必须先读取文件
|
||||
- 理解现有逻辑后再提出修改建议
|
||||
|
||||
- **破坏现有架构**
|
||||
|
||||
- 不随意移动目录结构
|
||||
- 不随意重构核心模块
|
||||
|
||||
- **随意改动换行符**
|
||||
- 遵循 `.gitattributes` 规则
|
||||
- 不混用 LF 和 CRLF
|
||||
|
||||
### 测试流程
|
||||
|
||||
- **跳过测试直接提交**
|
||||
- 修改后必须运行相关测试
|
||||
- 测试失败必须分析原因
|
||||
|
||||
### Git 操作
|
||||
|
||||
- **使用 `git commit --amend`**
|
||||
|
||||
- 除非用户明确要求
|
||||
- 总是创建新提交
|
||||
|
||||
- **使用 `git push --force`**
|
||||
|
||||
- 特别是推送到 main/master 分支
|
||||
- 如果用户要求，必须警告风险
|
||||
|
||||
- **跳过 hooks**
|
||||
- 不使用 `--no-verify`
|
||||
|
||||
### 过度工程
|
||||
|
||||
- **添加未要求的功能**
|
||||
|
||||
- 只做用户要求的修改
|
||||
- 不主动重构周边代码
|
||||
|
||||
- **添加不必要的注释**
|
||||
|
||||
- 不给自明的代码添加注释
|
||||
|
||||
- **过度抽象**
|
||||
- 不为一次性操作创建工具函数
|
||||
- 不为假设的未来需求设计
|
||||
|
||||
---
|
||||
|
||||
## 决策原则
|
||||
|
||||
### 何时需要确认
|
||||
|
||||
**必须确认**：
|
||||
|
||||
- 需求有歧义，存在多种理解
|
||||
- 有多个技术方案，需要权衡
|
||||
- 可能破坏兼容性
|
||||
- 涉及架构变更
|
||||
|
||||
**可以不确认**：
|
||||
|
||||
- 明显的 bug 修复
|
||||
- 符合现有模式的小改动
|
||||
- 测试用例补充
|
||||
|
||||
### 何时记录到 decisions.md
|
||||
|
||||
**必须记录**（ADR 格式）：
|
||||
|
||||
- 影响多个模块的架构决策
|
||||
- 技术栈选择
|
||||
- 设计模式选择
|
||||
- 重要的约束条件
|
||||
|
||||
---
|
||||
|
||||
## 沟通原则
|
||||
|
||||
### 输出风格
|
||||
|
||||
- 简洁明确，避免冗长
|
||||
- 使用纯文本结构化输出，必要时用 Markdown 代码块
|
||||
- 代码块标注语言
|
||||
- 不使用 emoji（除非用户明确要求）
|
||||
- 不使用过度的赞美或验证
|
||||
|
||||
### 技术准确性
|
||||
|
||||
- 优先技术准确性，而非迎合用户
|
||||
- 发现用户理解有误时，礼貌纠正
|
||||
- 不确定时，先调查再回答
|
||||
|
||||
### 时间估算
|
||||
|
||||
- 不给出时间估算
|
||||
- 专注于任务本身，让用户自己判断时间
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ def run_cli(*args, cwd=None):
|
|||
|
||||
|
||||
class PlanProgressCliTests(unittest.TestCase):
|
||||
def test_select_seeds_progress_when_missing(self):
|
||||
def test_select_prefers_in_progress(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
root = Path(tmp_dir)
|
||||
plans_dir = root / "docs" / "plans"
|
||||
|
|
@ -26,6 +26,13 @@ class PlanProgressCliTests(unittest.TestCase):
|
|||
(plans_dir / "2026-01-01-old.md").write_text("old", encoding="utf-8")
|
||||
(plans_dir / "2026-01-02-new.md").write_text("new", encoding="utf-8")
|
||||
|
||||
progress = root / "memory-bank" / "progress.md"
|
||||
progress.parent.mkdir(parents=True)
|
||||
progress.write_text(
|
||||
"[PLAN] docs/plans/2026-01-01-old.md | status=in-progress | date=2026-01-03\n",
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
result = run_cli(
|
||||
"select",
|
||||
"-plans",
|
||||
|
|
@ -35,17 +42,10 @@ class PlanProgressCliTests(unittest.TestCase):
|
|||
cwd=root,
|
||||
)
|
||||
|
||||
self.assertEqual(result.returncode, 0, msg=result.stderr)
|
||||
self.assertEqual(result.returncode, 0)
|
||||
self.assertEqual(result.stdout.strip(), "docs/plans/2026-01-01-old.md")
|
||||
|
||||
progress = root / "memory-bank" / "progress.md"
|
||||
text = progress.read_text(encoding="utf-8")
|
||||
self.assertIn("<!-- plan-status:start -->", text)
|
||||
self.assertIn("<!-- plan-status:end -->", text)
|
||||
self.assertIn("`2026-01-01-old.md` pending", text)
|
||||
self.assertIn("`2026-01-02-new.md` pending", text)
|
||||
|
||||
def test_select_returns_first_pending_in_order(self):
|
||||
def test_select_skips_done_and_blocked(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
root = Path(tmp_dir)
|
||||
plans_dir = root / "docs" / "plans"
|
||||
|
|
@ -58,12 +58,8 @@ class PlanProgressCliTests(unittest.TestCase):
|
|||
progress.write_text(
|
||||
"\n".join(
|
||||
[
|
||||
"# Plan 状态",
|
||||
"",
|
||||
"<!-- plan-status:start -->",
|
||||
"- [ ] `2026-01-02-b.md` pending",
|
||||
"- [ ] `2026-01-01-a.md` pending",
|
||||
"<!-- plan-status:end -->",
|
||||
"[PLAN] docs/plans/2026-01-02-b.md | status=done | date=2026-01-03",
|
||||
"[PLAN] docs/plans/2026-01-01-a.md | status=blocked | date=2026-01-03",
|
||||
"",
|
||||
]
|
||||
),
|
||||
|
|
@ -79,27 +75,13 @@ class PlanProgressCliTests(unittest.TestCase):
|
|||
cwd=root,
|
||||
)
|
||||
|
||||
self.assertEqual(result.returncode, 0, msg=result.stderr)
|
||||
self.assertEqual(result.stdout.strip(), "docs/plans/2026-01-02-b.md")
|
||||
self.assertNotEqual(result.returncode, 0)
|
||||
self.assertIn("no pending plans", (result.stdout + result.stderr).lower())
|
||||
|
||||
def test_record_updates_line(self):
|
||||
def test_record_creates_section(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
root = Path(tmp_dir)
|
||||
progress = root / "memory-bank" / "progress.md"
|
||||
progress.parent.mkdir(parents=True)
|
||||
progress.write_text(
|
||||
"\n".join(
|
||||
[
|
||||
"# Plan 状态",
|
||||
"",
|
||||
"<!-- plan-status:start -->",
|
||||
"- [ ] `2026-01-03-demo.md` pending",
|
||||
"<!-- plan-status:end -->",
|
||||
"",
|
||||
]
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
result = run_cli(
|
||||
"record",
|
||||
|
|
@ -109,13 +91,15 @@ class PlanProgressCliTests(unittest.TestCase):
|
|||
"done",
|
||||
"-progress",
|
||||
"memory-bank/progress.md",
|
||||
"-note",
|
||||
"done",
|
||||
cwd=root,
|
||||
)
|
||||
|
||||
self.assertEqual(result.returncode, 0, msg=result.stderr)
|
||||
self.assertEqual(result.returncode, 0)
|
||||
text = progress.read_text(encoding="utf-8")
|
||||
self.assertIn("- [x] `2026-01-03-demo.md` done", text)
|
||||
self.assertEqual(text.count("2026-01-03-demo.md"), 1)
|
||||
self.assertIn("## Plan 状态记录", text)
|
||||
self.assertIn("status=done", text)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
|
|
|||
|
|
@ -1,100 +0,0 @@
|
|||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
SCRIPT = ROOT / "scripts" / "playbook.py"
|
||||
|
||||
|
||||
def run_cli(*args):
|
||||
return subprocess.run(
|
||||
[sys.executable, str(SCRIPT), *args],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
|
||||
|
||||
class SyncDirectoryActionsTests(unittest.TestCase):
|
||||
def test_sync_memory_bank_adds_missing_files_without_deleting_custom(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
root = Path(tmp_dir)
|
||||
memory_bank = root / "memory-bank"
|
||||
memory_bank.mkdir(parents=True)
|
||||
custom = memory_bank / "custom.md"
|
||||
custom.write_text("custom", encoding="utf-8")
|
||||
|
||||
config_body = f"""
|
||||
[playbook]
|
||||
project_root = "{tmp_dir}"
|
||||
|
||||
[sync_memory_bank]
|
||||
project_name = "Demo"
|
||||
"""
|
||||
config_path = root / "playbook.toml"
|
||||
config_path.write_text(config_body, encoding="utf-8")
|
||||
|
||||
result = run_cli("-config", str(config_path))
|
||||
self.assertEqual(result.returncode, 0, msg=result.stderr)
|
||||
|
||||
self.assertTrue(custom.exists())
|
||||
self.assertTrue((memory_bank / "project-brief.md").is_file())
|
||||
|
||||
def test_sync_prompts_adds_missing_files_without_deleting_custom(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
root = Path(tmp_dir)
|
||||
prompts = root / "docs" / "prompts"
|
||||
prompts.mkdir(parents=True)
|
||||
custom = prompts / "custom.md"
|
||||
custom.write_text("custom", encoding="utf-8")
|
||||
|
||||
config_body = f"""
|
||||
[playbook]
|
||||
project_root = "{tmp_dir}"
|
||||
|
||||
[sync_prompts]
|
||||
"""
|
||||
config_path = root / "playbook.toml"
|
||||
config_path.write_text(config_body, encoding="utf-8")
|
||||
|
||||
result = run_cli("-config", str(config_path))
|
||||
self.assertEqual(result.returncode, 0, msg=result.stderr)
|
||||
|
||||
self.assertTrue(custom.exists())
|
||||
self.assertTrue((prompts / "system" / "agent-behavior.md").is_file())
|
||||
|
||||
def test_sync_memory_bank_force_overwrites_template_files_only(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
root = Path(tmp_dir)
|
||||
memory_bank = root / "memory-bank"
|
||||
memory_bank.mkdir(parents=True)
|
||||
custom = memory_bank / "custom.md"
|
||||
custom.write_text("custom", encoding="utf-8")
|
||||
|
||||
brief = memory_bank / "project-brief.md"
|
||||
brief.write_text("OLD", encoding="utf-8")
|
||||
|
||||
config_body = f"""
|
||||
[playbook]
|
||||
project_root = "{tmp_dir}"
|
||||
|
||||
[sync_memory_bank]
|
||||
project_name = "Demo"
|
||||
force = true
|
||||
no_backup = true
|
||||
"""
|
||||
config_path = root / "playbook.toml"
|
||||
config_path.write_text(config_body, encoding="utf-8")
|
||||
|
||||
result = run_cli("-config", str(config_path))
|
||||
self.assertEqual(result.returncode, 0, msg=result.stderr)
|
||||
|
||||
self.assertTrue(custom.exists())
|
||||
self.assertNotIn("OLD", brief.read_text(encoding="utf-8"))
|
||||
backups = list(memory_bank.glob("project-brief.md.bak.*"))
|
||||
self.assertEqual(backups, [])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
SCRIPT = ROOT / "scripts" / "playbook.py"
|
||||
|
||||
|
||||
def run_cli(*args):
|
||||
return subprocess.run(
|
||||
[sys.executable, str(SCRIPT), *args],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
|
||||
|
||||
class VendorSnapshotTemplatesTests(unittest.TestCase):
|
||||
def test_vendor_includes_core_templates(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
config_body = f"""
|
||||
[playbook]
|
||||
project_root = "{tmp_dir}"
|
||||
|
||||
[vendor]
|
||||
langs = ["tsl"]
|
||||
"""
|
||||
config_path = Path(tmp_dir) / "playbook.toml"
|
||||
config_path.write_text(config_body, encoding="utf-8")
|
||||
|
||||
result = run_cli("-config", str(config_path))
|
||||
self.assertEqual(result.returncode, 0, msg=result.stderr)
|
||||
|
||||
snapshot = Path(tmp_dir) / "docs/standards/playbook"
|
||||
self.assertTrue((snapshot / "templates/AGENTS.template.md").is_file())
|
||||
self.assertTrue((snapshot / "templates/AGENT_RULES.template.md").is_file())
|
||||
self.assertTrue((snapshot / "templates/README.md").is_file())
|
||||
self.assertTrue((snapshot / "templates/memory-bank").is_dir())
|
||||
self.assertTrue((snapshot / "templates/prompts").is_dir())
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Loading…
Reference in New Issue