zai-org / zai-org/feedback

[建议 / Feature] 向子进程环境注入 ZCODE_SESSION_ID,并为 zcode:// 协议增加会话恢复深链路由

Open
#465 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

priority: P2
Dominant language
No language data
Stars
22
Forks
1
PR merge metrics
No merged PRs in 30d

Description

背景

我在终端使用 ZCode CLI,并配合外部工具(笔记、任务管理、自动化脚本)管理大量 Agent 会话,希望实现「外部记录 → 一键回到某个会话」的工作流。目前有两个具体障碍。

现状

  1. 运行中的 Agent 无法得知自己的 sessionId。 Agent 的上下文与环境变量里都没有当前会话标识;目前只能通过扫描 ~/.zcode/cli/exec/ 目录、按最新写入时间推断,并发多个会话时会误判。

  2. zcode:// 协议没有会话路由。 ZCode.app(macOS)已在 Info.plist 注册 zcode:// scheme,但当前仅有 zcode://oauth/callbackzcode://payment/callback 两类回调路由,没有任何打开/恢复指定会话的路由。目前从外部恢复会话的唯一方式,是用户手工在终端执行 zcode --resume '<sessionId>'

建议

  1. 向子进程注入当前 sessionId 环境变量(如 ZCODE_SESSION_ID),与现有 ZCODE_ENVZCODE_PROCESS_LABEL 风格一致。这样 Agent 在向外部写入记录时能以第一方方式带上自己的会话标识,实现自动化的会话溯源,不再依赖目录推断。

  2. zcode:// 增加会话恢复深链,例如 zcode://resume?session=<sessionId>(或 zcode://open?session=<id>),行为为聚焦/打开 ZCode 并恢复指定会话。建议同时在文档中注明参数契约与找不到会话时的行为,便于第三方工具验证后接入。

期望收益

  • 外部笔记/任务工具可以保存「可点击回到该会话」的链接,点击即在 ZCode 中恢复上下文。
  • Agent 自身可第一方读取会话标识,自动记录「这段结论来自哪个会话」,后续可精确回溯。

环境信息

  • ZCode.app 3.10.2(macOS arm64,CFBundleURLTypes 已含 zcode scheme)
  • 已确认 app.asar 中 zcode:// 仅出现 oauth/payment 回调,无会话路由

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the existing oauth/callback and payment/callback routes in the macOS app, then inspect the zcode --resume entry point and how child-process environment variables are assembled. Done means a child process can read the session identifier and a documented zcode:// link focuses or resumes the requested session, with defined behavior for missing sessions.

Written by the indexing model from the issue text.

Assessment

Tech stack
macos
Domain
cli, desktop
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.