首页 项目目录 关于我们
Sign In
python
/
aceflow-pateoas-framework-main
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Branch: master
Branches Tags
aceflow-pate...
/
.aceflow
/
aceflow-pateoas-cli-use-guide.md

aceflow-pateoas-cli-use-guide.md 12 KB
Permalink History Raw

AceFlow-PATEOAS CLI 工具使用指南

目录

  1. 概述
  2. 环境准备
  3. 快速入门
  4. 命令参考
  5. 常见工作流示例
  6. 故障排除
  7. 高级配置
  8. 附录

1. 概述

AceFlow-PATEOAS CLI 工具是基于 AceFlow 流程框架与 PATEOAS 状态管理方法论的命令行接口，提供流程导航、状态管理、记忆操作等核心功能，支持完整流程、快速流程、变更流程和紧急流程四种工作模式。

核心功能

  • 智能流程分支决策
  • 阶段进度跟踪与更新
  • 异常状态记录与解决
  • AI 导航建议生成
  • 记忆池管理与检索

2. 环境准备

2.1 系统要求

  • Python 3.6 及以上版本
  • 操作系统：Windows/macOS/Linux

2.2 依赖安装

# 克隆项目仓库后执行
cd aceflow-project
pip install -r requirements.txt

2.3 环境验证

# 检查 Python 版本
python --version  # 应显示 3.6+

# 运行环境检查脚本
python check_env.py
# 成功输出：✅ 环境检查通过

3. 快速入门

3.1 初始化项目

# 创建新项目目录
mkdir aceflow-demo && cd aceflow-demo

# 初始化 AceFlow 项目结构
python aceflow_cli.py init

初始化成功后将创建以下目录结构：

.aceflow/
├── config/           # 配置文件目录
├── memory_pool/      # 记忆池存储
├── scripts/          # 核心脚本
├── templates/        # 流程模板
└── current_state.json # 当前状态文件

3.2 确定流程分支

# 分析任务描述并推荐流程分支
python aceflow_cli.py determine-workflow "开发用户注册功能模块"

输出示例：

推荐流程分支: 完整流程
阶段路径: S1 → S2 → S3 → S4 → S5 → S6 → S7 → S8
决策依据: 
- 任务包含"开发"关键词，判定为新功能开发
- 未检测到"紧急"、"修复"等特殊标识
- 任务复杂度评估: 中 (6/10)，适合完整流程

3.3 更新阶段进度

# 更新 S1 阶段进度至 100%（完成）
python aceflow_cli.py update-status S1 100

3.4 获取导航建议

python aceflow_cli.py get-suggestions

输出示例：

导航建议:
- [high] 阶段 S1 已完成，准备进入 S2

4. 命令参考

4.1 流程管理命令

determine-workflow

功能：根据任务描述自动分析并推荐流程分支
用法：python aceflow_cli.py determine-workflow "<任务描述>"
示例：

python aceflow_cli.py determine-workflow "修复登录页面验证码不显示问题"

输出：推荐流程分支及阶段路径

set-workflow

功能：手动设置流程分支
用法：python aceflow_cli.py set-workflow <流程类型>
流程类型：full_workflow（完整流程）、quick_workflow（快速流程）、change_workflow（变更流程）、emergency_workflow（紧急流程）
示例：

python aceflow_cli.py set-workflow quick_workflow

load-template

功能：加载指定阶段的模板文件
用法：python aceflow_cli.py load-template <阶段ID> [输出路径]
示例：

python aceflow_cli.py load-template S2 ./s2_tasks.md

4.2 状态管理命令

update-status

功能：更新指定阶段的进度
用法：python aceflow_cli.py update-status <阶段ID> <进度百分比>
示例：

python aceflow_cli.py update-status S4 75

get-status

功能：查询当前项目状态
用法：python aceflow_cli.py get-status [阶段ID]
示例：

# 查询所有阶段状态
python aceflow_cli.py get-status

# 查询特定阶段状态
python aceflow_cli.py get-status S3

record-abnormality

功能：记录异常状态
用法：python aceflow_cli.py record-abnormality <阶段ID> "<异常描述>" [--severity 严重度]
严重度：high（高）、medium（中，默认）、low（低）
示例：

python aceflow_cli.py record-abnormality S4 "用户注册接口返回500错误" --severity high

resolve-abnormality

功能：标记异常状态为已解决
用法：python aceflow_cli.py resolve-abnormality <异常ID>
示例：

python aceflow_cli.py resolve-abnormality ABN-202507101530

4.3 导航与建议命令

get-suggestions

功能：获取AI导航建议
用法：python aceflow_cli.py get-suggestions
示例：

python aceflow_cli.py get-suggestions

explain-decision

功能：解释最近一次流程决策依据
用法：python aceflow_cli.py explain-decision
示例：

python aceflow_cli.py explain-decision

4.4 记忆池命令

store-memory

功能：手动存储记忆片段
用法：python aceflow_cli.py store-memory <记忆类型> "<内容>" [--metadata key=value]
记忆类型：REQ（需求）、CON（约束）、TASK（任务）、CODE（代码）、TEST（测试）、DEFECT（缺陷）、FDBK（反馈）
示例：

python aceflow_cli.py store-memory REQ "用户要求支持手机号登录" --metadata source=PRD author=product_manager

retrieve-memory

功能：检索记忆片段
用法：python aceflow_cli.py retrieve-memory [--type 记忆类型] [--keywords 关键词]
示例：

# 检索所有需求记忆
python aceflow_cli.py retrieve-memory --type REQ

# 检索包含"登录"关键词的记忆
python aceflow_cli.py retrieve-memory --keywords 登录

4.5 工具命令

validate-config

功能：验证配置文件完整性
用法：python aceflow_cli.py validate-config [--check-templates]
示例：

# 基本配置验证
python aceflow_cli.py validate-config

# 包含模板文件验证
python aceflow_cli.py validate-config --check-templates

export-state

功能：导出当前状态数据
用法：python aceflow_cli.py export-state [输出文件路径]
示例：

python aceflow_cli.py export-state ./current_state_backup.json

import-state

功能：导入状态数据
用法：python aceflow_cli.py import-state <状态文件路径>
示例：

python aceflow_cli.py import-state ./current_state_backup.json

5. 常见工作流示例

5.1 新功能开发（完整流程）

# 1. 初始化项目
python aceflow_cli.py init

# 2. 确定流程分支
python aceflow_cli.py determine-workflow "开发用户注册功能"

# 3. 加载 S1 模板并编辑
python aceflow_cli.py load-template S1 ./s1_user_story.md
# 编辑 s1_user_story.md 文件...

# 4. 更新 S1 进度
python aceflow_cli.py update-status S1 100

# 5. 获取导航建议（自动进入 S2）
python aceflow_cli.py get-suggestions

# 6. 继续 S2 任务拆分...
python aceflow_cli.py load-template S2 ./s2_tasks.md

5.2 Bug 修复（快速流程）

# 1. 初始化项目（如已初始化可跳过）
python aceflow_cli.py init

# 2. 设置为快速流程
python aceflow_cli.py set-workflow quick_workflow

# 3. 加载 S2 模板（直接任务拆分）
python aceflow_cli.py load-template S2 ./s2_tasks.md

# 4. 更新开发进度
python aceflow_cli.py update-status S2 100
python aceflow_cli.py update-status S4 100  # 直接进入开发阶段

# 5. 记录测试结果
python aceflow_cli.py update-status S5 100

# 6. 完成进度汇总
python aceflow_cli.py update-status S8 100

5.3 需求变更处理

# 1. 记录需求变更记忆
python aceflow_cli.py store-memory FDBK "用户要求增加第三方登录功能"

# 2. 设置为变更流程
python aceflow_cli.py set-workflow change_workflow

# 3. 更新需求和任务
python aceflow_cli.py load-template S1 ./s1_user_story.md  # 更新用户故事
python aceflow_cli.py load-template S2 ./s2_tasks.md       # 更新任务拆分
python aceflow_cli.py load-template S3 ./s3_testcases.md   # 更新测试用例

# 4. 执行开发和测试
python aceflow_cli.py update-status S1 100
python aceflow_cli.py update-status S2 100
python aceflow_cli.py update-status S3 100
python aceflow_cli.py update-status S4 100

6. 故障排除

6.1 导入错误

错误信息：ImportError: attempted relative import beyond top-level package
解决方案：

# 1. 检查 __init__.py 文件是否存在
ls -la .aceflow/scripts/{__,core/__,cli/__,utils/__}init__.py

# 2. 确保 aceflow_cli.py 路径配置正确
cat aceflow_cli.py | grep sys.path.append

6.2 状态文件损坏

错误信息：JSONDecodeError: Expecting value: line 1 column 1 (char 0)
解决方案：

# 1. 尝试恢复备份
cp .aceflow/current_state.json.bak .aceflow/current_state.json

# 2. 如无备份，重新初始化状态
python aceflow_cli.py init --reset-state

6.3 命令不存在

错误信息：error: unrecognized arguments: new-command
解决方案：

# 1. 检查命令拼写
python aceflow_cli.py --help  # 查看所有可用命令

# 2. 更新到最新版本
git pull origin main

6.4 模板加载失败

错误信息：FileNotFoundError: [Errno 2] No such file or directory: '.aceflow/templates/stage_templates/s1_user_story.md'
解决方案：

# 1. 验证模板路径配置
cat .vscode/aceflow_agent.json | grep templates

# 2. 重新安装模板文件
python aceflow_cli.py install-templates

7. 高级配置

7.1 动态阈值调整

编辑 .aceflow/config/dynamic_thresholds.json 文件：

{
  "stage_specific": {
    "S4": {
      "unit_test_pass_rate": {
        "default": 90,
        "critical_task": 95,
        "minor_task": 85
      }
    }
  }
}

7.2 AI 决策信任度设置

编辑 .vscode/aceflow_agent.json 文件：

{
  "workflow_config": {
    "ai_trust_level": "L2",  // L1:仅建议, L2:低风险自动执行, L3:全流程自动决策
    "success_threshold": 0.85
  }
}

7.3 自定义流程分支

编辑 .aceflow/config/workflow_rules.json 文件，添加自定义流程：

{
  "workflow_rules": {
    "research_workflow": ["S1", "S3", "S7", "S8"]  // 调研类流程
  },
  "workflow_conditions": {
    "research_workflow": {
      "keywords": ["调研", "研究", "探索"],
      "complexity_threshold": 3
    }
  }
}

8. 附录

8.1 阶段 ID 与名称对应表

阶段 ID 名称 核心任务
S1 用户故事细化 将需求转化为用户故事
S2 任务拆分 将用户故事拆分为开发任务
S3 测试用例设计 设计测试用例
S4 功能实现 代码开发与单元测试
S5 测试报告 执行测试并生成报告
S6 代码评审 代码质量与规范评审
S7 演示与反馈 功能演示与反馈收集
S8 进度汇总 项目进度总结与规划

8.2 记忆类型说明

记忆类型 代码 描述 示例
需求记忆 REQ 记录用户需求和期望 用户需要支持手机号登录
约束记忆 CON 技术约束和限制条件 必须兼容IE11浏览器
任务记忆 TASK 任务相关信息 登录模块需在5月前完成
代码记忆 CODE 代码实现细节 使用JWT进行身份验证
测试记忆 TEST 测试相关信息 测试用例TC-001验证登录功能
缺陷记忆 DEFECT 缺陷和问题记录 登录接口在密码含特殊字符时失败
反馈记忆 FDBK 用户反馈信息 用户认为注册流程太复杂

8.3 常用命令速查表

任务 命令
初始化项目 python aceflow_cli.py init
选择流程分支 python aceflow_cli.py determine-workflow "任务描述"
更新阶段进度 python aceflow_cli.py update-status Sx 进度
获取导航建议 python aceflow_cli.py get-suggestions
记录异常 python aceflow_cli.py record-abnormality Sx "描述"
检索记忆 python aceflow_cli.py retrieve-memory --keywords 关键词
验证配置 python aceflow_cli.py validate-config