Imported from segzix/zhisuan (
AGENTS.md). Install upstream withnpx skills add segzix/zhisuan. Copyright stays with the author.
AGENTS.md
Workflow Summary / 工作流速查表
| Workflow | Name | Best used for | Example command |
|---|---|---|---|
| Workflow A | Read-Only Analysis | Understanding project structure, code logic, call chains, or root causes without editing files. | Use Workflow A: Analyze the current project structure and main call chain in read-only mode. Do not modify files. |
| Workflow B | Plan First, Then Wait | Getting a safe implementation plan before any code changes. | Use Workflow B: Analyze this issue and propose an implementation plan. Do not modify code directly. |
| Workflow C | Implement With Review | Normal feature implementation or bug fixing with code changes and final review. | Use Workflow C: Analyze and implement this feature, then ask reviewer to review the git diff. |
| Workflow D | Debug and Fix | Handling errors, failed commands, test failures, API errors, or runtime exceptions. | Use Workflow D: Diagnose and fix this error, then ask reviewer to review the changes. |
| Workflow E | Review Only | Reviewing current git diff, selected files, or provided code without modifying anything. |
Use Workflow E: Review the current git diff only. Do not modify files. |
| Workflow F | Research Then Plan | Checking external documentation, API behavior, library usage, or compatibility before planning. | Use Workflow F: Research the relevant documentation first, then propose an implementation plan. Do not modify code directly. |
| Workflow G | Refactor Safely | Refactoring a module or component while preserving existing behavior. | Use Workflow G: Safely refactor this module while preserving behavior, then review the diff. |
| Workflow H | Add Tests | Adding or improving tests for an existing feature or bug fix. | Use Workflow H: Add tests for this feature and run the relevant test commands. |
| Workflow I | Local Bridge / Provider Debugging | Debugging OpenCode, uvicorn bridge, model routing, API keys, base URLs, SSL, or streaming issues. | Use Workflow I: Debug the OpenCode local uvicorn bridge failure. Do not expose keys. |
| Workflow J | Quick Small Change | Very small, low-risk changes that do not require a full planning stage. | Use Workflow J: Make this small change, then ask reviewer to review the diff. |
MCP Server Tools / MCP 工具总表
All MCP server tools available to this project should be recorded in this section. These tools are part of the normal agent workflow. When a workflow encounters a file type, data source, or task that matches one of these tools, the agent should automatically use the appropriate MCP tool instead of asking the user to perform manual preprocessing.
| MCP Server | Tool | Best used for | Auto-use condition | Output / constraint |
|---|---|---|---|---|
pdf-tools |
pdf_to_text |
Convert PDF documents into text for downstream analysis. | Automatically use when a workflow needs to read, summarize, analyze, or extract information from a .pdf file. |
Save extracted text under docs_extracted/; do not modify the original PDF. |
pdf-tools |
read_text_preview |
Quickly preview extracted .txt or .md files. |
Automatically use after text extraction, or when a large text document only needs an initial inspection. | Return a bounded preview first; use normal file reading for deeper analysis if needed. |
image-tools |
read_image |
Read and extract text/OCR content from image files (.jpg, .png, .gif, .bmp, etc.). |
Automatically use when the user references an image file and the model cannot natively view images. | Extract visual content as text description; do not modify the original image. |
MCP Auto Invocation Rule
MCP tools are workflow tools, not separate manual steps.
When executing any workflow:
- Check whether the task matches an available MCP tool.
- If a matching MCP tool exists and the operation is read-only or produces a safe derived artifact, use it automatically.
- Do not ask the user to manually convert, preprocess, or inspect files when an MCP tool can do it.
- Do not claim that a file cannot be read before checking relevant MCP tools.
- Save generated derived artifacts under a clearly named project subdirectory such as
docs_extracted/. - Never modify original source documents unless explicitly requested.
- For tools that may modify source files, delete files, call external services, or perform costly operations, ask the user first.
- After using an MCP tool, continue the selected workflow using the generated or returned artifact.
This file defines how OpenCode agents should work in this project.
Workflow Usage
The user may choose one of the workflows above by name. When a workflow is selected, follow the corresponding role sequence and constraints.
Workflow A: Read-Only Analysis
只读分析:用于理解项目结构、调用链、错误原因或设计逻辑,不修改文件。
Use this workflow when the user only wants to understand the project, code structure, error cause, or design logic.
Role sequence:
planner
Rules:
- Do not edit files.
- Do not run destructive commands.
- Inspect only relevant files.
- Explain the project structure, call chain, or root cause clearly.
- End with a concise conclusion and optional next steps.
Example user command:
Use Workflow A: analyze the current project structure and main call chain without modifying files.
Workflow B: Plan First, Then Wait
先规划后等待:用于高风险或不确定任务,先给方案,等用户确认后再实现。
Use this workflow when the user wants a safe implementation plan before any code change.
Role sequence:
planner- Stop and wait for user confirmation.
Rules:
- Do not edit files.
- Do not run modification commands.
- Identify relevant files.
- Explain the root cause.
- Provide a minimal implementation plan.
- Explicitly list which files would be changed.
- Wait for user approval before using
coder.
Example user command:
Use Workflow B: analyze this issue and produce a modification plan without directly changing code.
Workflow C: Implement With Review
实现并审查:用于常规开发任务,先规划,再编码,最后审查 diff。
Use this workflow for normal coding tasks where code modification is expected.
Role sequence:
plannercoderreviewer
Rules:
plannerfirst analyzes the task and proposes a minimal plan.coderimplements only the approved or clearly necessary changes.codershould keep changes small and scoped.reviewerreviewsgit diffafter implementation.- Final response must include:
- files changed
- why they were changed
- verification performed
- remaining risks or manual checks
Example user command:
Use Workflow C: analyze and implement this feature, then ask reviewer to review the git diff.
Workflow D: Debug and Fix
定位并修复:用于报错、测试失败、API 错误或运行时异常,先定位原因再修复。
Use this workflow when there is an error log, failing command, test failure, API error, or runtime exception.
Role sequence:
debuggerplannercoderreviewer
Rules:
debuggerfirst analyzes the error and identifies the likely cause.debuggermay suggest diagnostic commands, but should explain them before running.plannerconverts the diagnosis into a minimal fix plan.coderapplies the fix.reviewerreviews the final diff.- Do not guess if the issue can be verified with a focused command.
Example user command:
Use Workflow D: diagnose this error, fix it, and ask reviewer to review the final diff.
Workflow E: Review Only
只审查:用于提交前检查或代码质量审查,不产生新的代码修改。
Use this workflow when the user only wants code review and does not want modifications.
Role sequence:
reviewer
Rules:
- Do not edit files.
- Review current
git diff, selected files, or provided code. - Focus on:
- correctness
- maintainability
- security
- compatibility
- regression risk
- unintended changes
- Provide actionable comments.
- Do not rewrite the code unless explicitly requested.
Example user command:
Use Workflow E: review the current git diff without modifying files.
Workflow F: Research Then Plan
先查资料再规划:用于需要查外部文档、API 行为、框架用法或兼容性的问题。
Use this workflow when external documentation, API behavior, framework usage, or library compatibility needs to be checked.
Role sequence:
researcherplanner- Stop and wait for user confirmation.
Rules:
researcherchecks relevant documentation or references.researchermust not edit files.plannersummarizes findings and proposes an implementation plan.- Do not implement until the user confirms.
Example user command:
Use Workflow F: check relevant documentation, then propose an implementation plan without changing code.
Workflow G: Refactor Safely
安全重构:用于重构模块或整理结构,要求保持原有行为不变。
Use this workflow for refactoring tasks.
Role sequence:
plannercoderdebuggerreviewer
Rules:
planneridentifies the current structure and refactoring scope.- Refactor only the requested area.
- Preserve public behavior.
- Do not introduce unrelated style changes.
coderapplies small incremental changes.debuggerruns or suggests focused verification.reviewerchecks whether behavior was preserved.
Example user command:
Use Workflow G: refactor this module safely, preserve behavior, and review the final diff.
Workflow H: Add Tests
补充测试:用于为功能、bug 修复或边界行为补充测试,并验证测试质量。
Use this workflow when adding or improving tests.
Role sequence:
plannercoderdebuggerreviewer
Rules:
planneridentifies the behavior that should be tested.coderadds minimal focused tests.debuggerruns the relevant test command or explains why it cannot run.reviewerchecks whether tests are meaningful and not brittle.
Example user command:
Use Workflow H: add focused tests for this feature and run the relevant tests.
Workflow I: Local Bridge / Provider Debugging
本地 bridge / provider 排错:用于 OpenCode、uvicorn bridge、模型路由、key、base URL、SSL、streaming 等问题。
Use this workflow for OpenCode, uvicorn bridge, model provider, API key, base URL, model routing, or streaming issues.
Role sequence:
debuggerplannercoderreviewer
Rules:
- First determine whether the issue is:
- local bridge authentication
- upstream API key
- base URL
- endpoint path
- model name
- SSL verification
- request schema
- response parsing
- streaming behavior
- Never print real API keys.
- Check whether the model is allowed by the local bridge whitelist.
- Use focused curl commands when useful.
- If code changes are needed, keep them minimal.
reviewermust check that GPT, Claude, and unsupported-model behavior are not broken.
Example user command:
Use Workflow I: debug why OpenCode cannot call the local uvicorn bridge without exposing keys.
Workflow J: Quick Small Change
快速小修改:用于非常小、低风险、目标明确的修改,若范围扩大则切换到 Workflow C。
Use this workflow for very small, low-risk changes.
Role sequence:
coderreviewer
Rules:
- Only use this workflow when the change is clearly small.
codershould explain the intended change before editing.reviewerchecks the final diff.- If the task is not actually small, switch to Workflow C.
Example user command:
Use Workflow J: make this small change and ask reviewer to check the diff.
Workflow Selection Rule
If the user explicitly names a workflow, follow that workflow.
If the user does not name a workflow:
- Use Workflow A for explanation-only questions.
- Use Workflow B when the task is unclear or risky.
- Use Workflow C for normal implementation tasks.
- Use Workflow D for errors, failures, and exceptions.
- Use Workflow E for review-only requests.
- Use Workflow F when external documentation is needed.
- Use Workflow I for model provider, API bridge, OpenCode, or local uvicorn issues.
When uncertain, choose the safer workflow and start with planner.
Project Working Principle
For any non-trivial task, do not directly modify files. First understand the project structure, identify the relevant files, explain the cause of the problem, then propose a minimal implementation plan.
Use the configured agents according to their roles:
planner: analyze the project, inspect relevant files, and produce an implementation plan. Do not modify files.coder: implement approved changes by editing files and running focused verification commands.debugger: investigate errors, inspect logs, run diagnostic commands, and propose fixes.reviewer: review code changes for correctness, maintainability, security, compatibility, and regressions. Do not modify files.researcher: search documentation or external references when needed. Do not modify files.
The current OpenCode configuration maps these roles to different models:
planner,debugger, andresearcheruse DeepSeek directly.coderuses GPT through the local uvicorn bridge.revieweruses Claude through the local uvicorn bridge.
Default Workflow
For complex coding tasks, follow this workflow:
-
Use
plannerfirst.- Read the project structure and relevant files.
- Identify the root cause or design problem.
- Produce a concise plan.
- Do not modify files.
-
Use
coderonly after the plan is clear.- Modify only the necessary files.
- Keep patches small and reviewable.
- Explain what will be changed before editing.
- Do not rewrite unrelated code.
-
Use
debuggerwhen there are errors.- Inspect logs, stack traces, command output, and configuration.
- Suggest focused verification commands.
- Ask before running commands that may take time or change state.
- Do not guess when the issue can be verified.
-
Use
reviewerbefore final completion.- Review
git diff. - Check for unintended changes.
- Check security, compatibility, maintainability, and regression risks.
- Do not modify files directly.
- Review
-
Summarize the final result.
- State what changed.
- State what was verified.
- State what still needs manual confirmation, if any.
Safety Rules
Never expose, print, copy, summarize, or modify real API keys or secrets.
Do not read these files unless explicitly instructed:
.env.env.*- files containing API keys, tokens, passwords, credentials, or private keys
Do not run destructive commands unless explicitly requested by the user. This includes:
rm -rf
sudo
git reset --hard
git clean -fd
chmod -R
chown -R
Do not push code automatically:
git push
Always ask before:
- editing files
- installing packages
- running long commands
- modifying configuration files
- changing model/provider routing
- deleting files
- changing environment variables
- running commands outside the current project directory
File Editing Rules
When modifying files:
- Change the smallest necessary scope.
- Preserve the existing project structure.
- Preserve naming conventions and code style.
- Do not introduce unrelated refactors.
- Do not change public behavior unless the task requires it.
- Do not silently remove existing features.
- Do not modify generated files unless necessary.
- After editing, inspect the diff.
Before final response, run or suggest:
git status
git diff
Debugging Rules
When debugging a failure, check in this order:
- Reproduce the error.
- Identify the failing command, endpoint, file, or function.
- Inspect the minimal relevant code path.
- Check environment variables and configuration names without revealing secret values.
- Check request path, model name, base URL, API type, and response parsing.
- Propose the smallest fix.
- Verify the fix with a focused command.
For model provider or bridge issues, check:
- API key existence, not the raw key value.
- Base URL.
- Endpoint path.
- Model name.
- Request body schema.
- Response body schema.
- Streaming vs non-streaming behavior.
- SSL verification settings.
- Local bridge authentication.
- Upstream provider routing.
Response Style
When responding, be concise but complete.
For code changes, include:
- files changed
- reason for each change
- verification performed
- remaining risks or manual checks
Do not over-explain obvious code. Focus on the decisions that matter.