# Cloud - GEO-SEO Optimizer 规范流程

> KIMI-2.5 持续开发系统标准操作程序 (SOP)
> 版本: 1.0.0 | 更新: 2026-02-13

---

## 六步循环工作流程

```
    ┌─────────────────────────────────────────────────────────┐
    │                                                         │
    ▼                                                         │
┌─────────┐    ┌─────────┐    ┌─────────┐                    │
│ 1. INIT │───▶│ 2. PICK │───▶│ 3. CODE │                    │
│  初始化  │    │  领任务  │    │  编码   │                    │
└─────────┘    └─────────┘    └────┬────┘                    │
                                   │                         │
                                   ▼                         │
┌─────────┐    ┌─────────┐    ┌─────────┐                    │
│ 6. PUSH │◀───│ 5. LOG  │◀───│ 4. TEST │                    │
│  提交   │    │  记录   │    │  测试   │                    │
└─────────┘    └─────────┘    └─────────┘                    │
     │                                                       │
     └───────────────────────────────────────────────────────┘
```

---

## 步骤详解

### Step 1: INIT - 初始化 (5分钟)

**执行命令:**
```bash
./init.sh
```

**检查清单:**
- [ ] 确认工作目录正确 (`pwd`)
- [ ] Python 3.11+ 可用
- [ ] 依赖已安装 (`pip list | grep -E "pydantic|typer|rich"`)
- [ ] task.json 可读
- [ ] progress.txt 最后 20 行已查看

**输出要求:**
- 显示当前任务统计
- 标记阻塞项（如有）
- 推荐下一个任务

---

### Step 2: PICK - 领任务 (5分钟)

**执行命令:**
```bash
python3 << 'EOF'
import json
with open('task.json') as f:
    data = json.load(f)

# 找 pending 且依赖满足的任务
pending = [t for t in data['tasks'] if t['status'] == 'pending']
for task in pending:
    deps = task['dependencies']
    deps_done = all(
        any(t2['id'] == d and t2['status'] == 'completed' for t2 in data['tasks'])
        for d in deps
    )
    if deps_done:
        print(f"推荐任务: {task['id']} - {task['title']}")
        print(f"预计耗时: {task['estimated_minutes']} 分钟")
        print(f"验收标准: {len(task['acceptance_criteria'])} 条")
        break
EOF
```

**决策规则:**
1. 优先选择 `status: pending` 的任务
2. 确认所有 `dependencies` 已完成
3. 检查 estimated_minutes <= 60
4. 如不满足，查看 `progress.txt` 确认阻塞原因

**领任务后必须执行:**
```bash
python3 -c "
import json
with open('task.json', 'r') as f:
    data = json.load(f)
for t in data['tasks']:
    if t['id'] == 'TASK_ID':
        t['status'] = 'in_progress'
        t['started_at'] = '2026-02-13THH:MM:SS'
data['active_task'] = 'TASK_ID'
with open('task.json', 'w') as f:
    json.dump(data, f, indent=2)
"
```

---

### Step 3: CODE - 编码 (30-60分钟)

**开始前读取:**
```bash
# 读取任务详情
python3 -c "
import json
with open('task.json') as f:
    data = json.load(f)
task = next(t for t in data['tasks'] if t['id'] == 'TASK_ID')
print(f'任务: {task[\"title\"]}')
print(f'描述: {task[\"description\"]}')
print('验收标准:')
for ac in task['acceptance_criteria']:
    print(f'  - {ac}')
"
```

**编码规范:**
1. **文件创建**: 严格按 `description` 中的路径创建
2. **类型注解**: 所有函数参数和返回值必须注解
3. **Docstring**: 每个公共函数必须有文档字符串
4. **错误处理**: 所有 I/O 操作必须有 try-except
5. **异步**: I/O 操作使用 async/await

**代码模板:**
```python
"""模块简短描述.

详细描述...
"""
from typing import Dict, Any, Optional
import asyncio

from utils.logger import get_logger

logger = get_logger(__name__)


class MyClass:
    """类文档字符串."""

    def __init__(self, config: Optional[Dict[str, Any]] = None) -> None:
        """初始化.

        Args:
            config: 配置字典
        """
        self.config = config or {}

    async def do_something(self, input: str) -> Dict[str, Any]:
        """做某事.

        Args:
            input: 输入字符串

        Returns:
            结果字典

        Raises:
            ValueError: 输入无效时
        """
        try:
            # 实现代码
            result = {"status": "ok"}
            return result
        except Exception as e:
            logger.error(f"操作失败: {e}")
            raise
```

**禁止事项:**
- ❌ 不要修改未指派给你的任务
- ❌ 不要重构无关代码
- ❌ 不要添加计划外功能
- ❌ 单次会话不要领多个任务

---

### Step 4: TEST - 测试 (10-15分钟)

**必做测试:**
```bash
# 1. 语法检查
python3 -m py_compile src/module/file.py

# 2. 导入测试
python3 -c "from src.module.file import MyClass; print('✓ 导入成功')"

# 3. 单元测试 (如有)
python3 -m pytest tests/test_module/test_file.py -v

# 4. 类型检查
python3 -m mypy src/module/file.py --ignore-missing-imports

# 5. 功能验证 (按验收标准逐项检查)
python3 << 'EOF'
# 编写验证脚本
from src.module.file import MyClass

# 测试用例 1
obj = MyClass()
result = obj.method()
assert result["key"] == "expected", "测试失败: ..."

print("✓ 所有验收标准通过")
EOF
```

**验收标准检查:**
逐项核对 task.json 中的 `acceptance_criteria`，全部通过才能进入下一步。

---

### Step 5: LOG - 更新记录 (5分钟)

**更新 task.json:**
```bash
python3 -c "
import json
from datetime import datetime

with open('task.json', 'r') as f:
    data = json.load(f)

# 标记任务完成
for t in data['tasks']:
    if t['id'] == 'TASK_ID':
        t['status'] = 'completed'
        t['completed_at'] = datetime.now().isoformat()

data['active_task'] = None
data['completed_count'] = sum(1 for t in data['tasks'] if t['status'] == 'completed')

with open('task.json', 'w') as f:
    json.dump(data, f, indent=2)

print(f'任务 {TASK_ID} 已完成')
print(f'总进度: {data[\"completed_count\"]}/{data[\"total_count\"]}')
"
```

**追加到 progress.txt:**
```bash
cat >> progress.txt << 'EOF'

[SESSION-XXX] YYYY-MM-DD - TASK_ID 完成
--------------------------------------------------------------------------------
状态: ✅ 已完成

完成内容:
  - 具体完成项 1
  - 具体完成项 2

代码变更:
  - 新增: src/xxx.py (XX 行)
  - 修改: src/yyy.py

测试情况:
  - 单元测试: X 个通过
  - 覆盖率: XX%

遇到的问题:
  - 问题描述及解决方案

下一步:
  - 推荐下一任务

EOF
```

---

### Step 6: PUSH - 提交代码 (5分钟)

**Git 提交流程:**
```bash
# 1. 检查状态
git status

# 2. 添加相关文件 (不要 add -A)
git add src/module/new_file.py
git add tests/test_module/test_new.py
git add task.json progress.txt

# 3. 创建提交
 git commit -m "$(cat <<'EOF'
feat: TASK_ID - 简短描述

- 详细变更点 1
- 详细变更点 2
- 验收标准全部通过

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

# 4. 推送 (如配置了远程)
git push origin main
```

**提交信息规范:**
- `feat:` 新功能
- `fix:` 修复
- `test:` 测试相关
- `docs:` 文档
- `refactor:` 重构

**必须包含:**
- TASK_ID
- 简短描述
- Co-Authored-By 行

---

## 上下文重置协议

每次新会话**必须**执行:

```bash
# 1. 重置上下文
clear

# 2. 确认目录
pwd  # /Users/hammer/Desktop/auto

# 3. 运行初始化
./init.sh

# 4. 查看进度
tail -30 progress.txt

# 5. 领任务
# ... 按 Step 2 执行
```

**禁止:**
- 不运行 init.sh 直接开始编码
- 假设知道当前任务状态
- 依赖上一次会话的上下文

---

## 阻塞处理流程

**遇到阻塞时:**

1. **记录阻塞** (progress.txt)
```
阻塞记录:
  任务: TASK_ID
  问题: 具体描述
  尝试: 已尝试的解决方案
  需要: 什么帮助或决策
```

2. **标记任务状态** (task.json)
```json
{
  "id": "TASK_ID",
  "status": "blocked",
  "block_reason": "依赖 API Key 未配置"
}
```

3. **切换任务**
- 选择同阶段其他 pending 任务
- 或选择前一阶段的遗留任务

4. **求助标记**
- 如阻塞超过 2 个会话未解决
- 在 progress.txt 添加 `[HELP]` 标记

---

## 浏览器验证 (可选增强)

对于需要验证的功能，使用 Playwright:

```python
# 在测试文件中
import pytest
from playwright.async_api import async_playwright

async def test_feature_in_browser():
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()

        # 验证逻辑
        await page.goto("http://localhost:8000")
        # ...

        await browser.close()
```

---

## 附录: 快速参考

### 常用命令

```bash
# 查看当前任务
python3 -c "import json; data=json.load(open('task.json')); print('Active:', data['active_task']); print('Completed:', data['completed_count'])"

# 查看待处理任务
python3 -c "import json; data=json.load(open('task.json')); [print(f\"{t['id']}: {t['title']}\") for t in data['tasks'] if t['status'] == 'pending']"

# 运行所有测试
python3 -m pytest tests/ -v --cov=src --cov-report=term-missing

# 类型检查
python3 -m mypy src/ --ignore-missing-imports

# 代码格式化
python3 -m black src/ tests/
```

### 文件清单

| 文件 | 用途 | 更新者 |
|-----|------|-------|
| task.json | 任务清单 | init.sh / 开发流程 |
| progress.txt | 工作日志 | 开发者 |
| cloud.md | 规范流程 | 维护者 |
| init.sh | 环境初始化 | 维护者 |
