Skip to content

Latest commit

 

History

History
43 lines (39 loc) · 3.23 KB

GEMINI.md

File metadata and controls

43 lines (39 loc) · 3.23 KB

ZX CLI 协作准则 (正式开源项目模式)

项目定位

  • 项目名称：ZX CLI (ZhiXing / 知行)。
  • Slogan：知行合一，极致执行。
  • 目标：构建一个模块化、生产级、具备全栈办公自动化与本地 RAG 记忆能力的 LangGraph 智能体 CLI。
  • 主要受众：中文开发者社区。
  • 核心特性：
    • 🧠 Memory 2.0：自动归档、向量检索 (LanceDB)、长期/情景记忆分离。
    • 📂 File I/O 2.1：原生支持 Office/PDF 解析、全文搜索、原子级精准修改。
    • 🛠️ Office Automation：Excel 报表生成、PPT 图文自动排版。
    • ⚡ Interactive：流式 Markdown 渲染、优雅中断、多线程交互、模型中立。

协作准则 (Agent 行为规范)

  1. 角色边界 (Critical)：

    • 开发者 Agent (Me/Gemini CLI)：我是项目的构建者，拥有修改核心代码、提交 Git、更新文档的权限。
    • 应用 Agent (It/ZX CLI)：它是项目产出的产品。必须将其视为“被隔离的员工”。其工具权限仅限于 output/ (产出) 和 tmp/ (临时)，绝不允许其具备修改自身代码或项目根目录的能力。
    • 原则：在编写 agent_core 时，必须以“防御性编程”对待 ZX CLI，锁死其权限。

  2. 稳健开发：在修改 agent_core 等核心代码前，需详细排查现有逻辑，严禁随意删除或破坏已有的稳健逻辑。

  3. 测试保障：新增功能或修改代码后，必须运行 tests/ 目录下的测试脚本，确保现有功能不被破坏（确保无回归 Bug）。

  4. 中文优先 (重点)：

    • 代码注释：所有新增或修改的代码，其注释必须使用简洁、专业的中文。
    • 文档编写：README、技能说明（SKILL.md）以及代码中的 Docstrings 必须以中文为主，确保对中文用户友好。

  5. 开源规范：

    • 遵循 Python PEP 8 代码风格规范。
    • 严禁将 API Keys、个人隐私信息、本地绝对路径等内容硬编码在代码或提交记录中。

  6. 版本管理：

    • 保持 Git 提交记录的语义化与整洁。
    • 关键操作前建议先向用户确认。

  7. 架构分层严守 (反省)：

    • 关注点分离：tools.py 仅允许存放直接暴露给 LLM 的 @tool 函数。
    • 拒绝惰性开发：严禁将系统级辅助逻辑（如文件扫描、YAML 解析、配置加载）混入工具层，必须剥离至 utils.py 或独立模块。
    • 先思考再落笔：新增功能时，必须先评估其在架构中的位置，而非为了省事就近编写。

  8. 提交规范 (刚性)：

    • 四部曲：Git 提交前必须完成四件事：1. 运行并通过测试；2. 更新 README.md (反映功能变更)；3. 更新 HANDOVER.md (记录日志)；4. 提交并 Push 到远程仓库。缺一不可。

用户与背景记忆

  • 用户名：宁可
  • 参考项目：openclaw_repo (已克隆在项目根目录，作为核心架构参考)。
  • 最新状态：
    • 详细开发日志与每日进度请查阅 HANDOVER.md。
    • 当前版本 v1.7+，已完成架构模块化重构与品牌升级，正处于办公自动化与多模态能力的深度迭代期。