docs(pi): document PI 2.5 PI_* env vars for Agent subprocesses#1226
Merged
docs(pi): document PI 2.5 PI_* env vars for Agent subprocesses#1226
Conversation
Align Project Interface docs and interface.schema.json with issue #1225: PI_INTERFACE_VERSION, PI_CLIENT_*, PI_VERSION, PI_CONTROLLER, PI_RESOURCE. Made-with: Cursor
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - 我在这里给出一些整体性的反馈：
- 当
agent是数组（多个子进程）时，最好能明确说明它们是否都会接收到相同的PI_CONTROLLER/PI_RESOURCE值，或者是否预期存在按代理（per-agent）的选择语义。 - 对于
PI_CONTROLLER和PI_RESOURCE，建议显式说明预期的字符编码和 JSON 转义规则（例如 UTF-8，如何处理非 ASCII 字符和引号），以便不同的 Client 和 Agent 实现能够一致地序列化/解析这些环境变量值。
面向 AI 代理的提示（Prompt）
Please address the comments from this code review:
## Overall Comments
- When `agent` is an array (multiple subprocesses), it would help to clarify whether all of them receive the same `PI_CONTROLLER`/`PI_RESOURCE` values or if there is any per-agent selection semantics expected.
- For `PI_CONTROLLER` and `PI_RESOURCE`, consider explicitly specifying the expected character encoding and JSON escaping rules (e.g., UTF-8, how to handle non-ASCII and quotes) so different Client and Agent implementations serialize/parse these environment values consistently.帮我变得更有用！请在每条评论上点 👍 或 👎，我会根据你的反馈改进后续的审查建议。
Original comment in English
Hey - I've left some high level feedback:
- When
agentis an array (multiple subprocesses), it would help to clarify whether all of them receive the samePI_CONTROLLER/PI_RESOURCEvalues or if there is any per-agent selection semantics expected. - For
PI_CONTROLLERandPI_RESOURCE, consider explicitly specifying the expected character encoding and JSON escaping rules (e.g., UTF-8, how to handle non-ASCII and quotes) so different Client and Agent implementations serialize/parse these environment values consistently.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- When `agent` is an array (multiple subprocesses), it would help to clarify whether all of them receive the same `PI_CONTROLLER`/`PI_RESOURCE` values or if there is any per-agent selection semantics expected.
- For `PI_CONTROLLER` and `PI_RESOURCE`, consider explicitly specifying the expected character encoding and JSON escaping rules (e.g., UTF-8, how to handle non-ASCII and quotes) so different Client and Agent implementations serialize/parse these environment values consistently.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR documents the new PI v2.5.0 convention for PI_* environment variables that a Client/UI should inject when launching Agent subprocesses, and aligns the Project Interface JSON schema descriptions with that documentation.
Changes:
- Added PI v2.5.0 entry and a new “Agent subprocess environment variables” section to the English Project Interface V2 documentation.
- Clarified the distinction between
interface_version(major JSON structure version) and the PI documentation’s semantic versioning (e.g. v2.5.0). - Updated
tools/interface.schema.jsondescriptions to point readers to the new PI v2.5.0PI_*environment variable convention.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| tools/interface.schema.json | Adds v2.5.0 notes in schema descriptions to guide Clients to inject PI_* env vars for Agent subprocesses and clarifies interface_version meaning. |
| docs/en_us/3.3-ProjectInterfaceV2.md | Documents PI v2.5.0 PI_* environment variables convention and clarifies versioning semantics in the English PI spec. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Align Project Interface docs and interface.schema.json with issue #1225: PI_INTERFACE_VERSION, PI_CLIENT_*, PI_VERSION, PI_CONTROLLER, PI_RESOURCE.
@MaaXYZ/ui-developers
fix #1225
Summary by Sourcery
为 Agent 子进程撰写 PI v2.5.0 环境变量约定的文档，并在接口版本相关的 schema/文档中进行统一。
Enhancements:
interface.schema.json，以反映澄清后的interface_version含义，以及在适用场景下新的 PI 环境变量约定。Documentation:
PI_*环境变量，包括客户端元数据以及选定的 controller/resource 上下文。interface.json中的interface_version是一个固定的 JSON Schema 主版本号，与 PI 文档的语义化版本号不同，并据此更新英文和中文的 PI 文档。Original summary in English
Summary by Sourcery
Document PI v2.5.0 environment variable conventions for Agent subprocesses and align the schema/docs around interface versioning.
Enhancements:
Documentation: