diff --git a/suite-developer/AGENTS.md b/suite-developer/AGENTS.md
index b22a7c8..24002d1 100644
--- a/suite-developer/AGENTS.md
+++ b/suite-developer/AGENTS.md
@@ -4,6 +4,20 @@
 
 ## 开发流程
 
+### 0. 理解执行环境
+
+你的脚本最终跑在**用户本地的 Docker 容器**里。数据流如下：
+
+```
+你的代码 → 打包为脚本包 → 发布到套件市场
+                               ↓
+用户执行套件 → gis-actions 从市场下载脚本包 → docker run
+→ 用户本地文件挂载到容器内 → 脚本处理 → 结果写入 /tmp/output/
+→ 脚本包销毁 → 结果留在用户机器
+```
+
+**用户不上传文件，永远提供本地路径。**
+
 ### 1. 分析需求
 用户需要什么处理能力？输入是什么？期望输出是什么？
 
@@ -30,7 +44,7 @@
 
 ```
 agc suites search <关键词>     # 搜索已有套件
-agc suites search <关键词>     # 搜索已有套件
+agc suites list               # 列出所有套件
 ```
 
 能找到现成的 Suite 就复用——用 `suite_id` 引用即可。
@@ -39,15 +53,31 @@ agc suites search <关键词>     # 搜索已有套件
 不要每次从头造轮子。复用 = 少写代码 + 少出 bug。
 
 ### 3. 设计套件
-- 有现成 Suite → 在 workflow.yaml 中用 `type: script` + `package_url` 引用
+- 有现成 Suite → 在 workflow.yaml 中用 `type: script` + `suite_id` 引用
 - 没有现成 Suite → 写自己的脚本，发布为新 Suite
 - 多个步骤串联 → 组成 Suite
+- **参数设计**：所有输入文件路径用参数传递，不硬编码路径
 
 ### 4. 实现
 写 workflow.yaml + scripts/run.py。
 
+```yaml
+# workflow.yaml 参数设计示例
+params:
+  type: object
+  required: ["input_path"]
+  properties:
+    input_path:
+      type: string
+      description: "输入文件路径（用户本地的 .shp 或 .geojson 文件）"
+    buffer_distance:
+      type: number
+      default: 100
+      description: "缓冲区半径（米）"
+```
+
 ### 5. 测试
-`agc run` 验证结果。
+`agc run` 验证结果。传入本地测试文件路径即可。
 
 ### 6. 发布
 `agc publish` → 合规检测 → 上线。