Skip to content

docs(design): KAL_TERM_CONTROL — terminal mode word gains control keystrokes, with the cross-repo plan - #37

Closed
Sunrisepeak wants to merge 1 commit into
mainfrom
term-control-design
Closed

Sunrisepeak wants to merge 1 commit into
mainfrom
term-control-design

Conversation

@Sunrisepeak

Copy link
Copy Markdown
Member

设计提案,不含实现。完整设计与任务依赖图:.agents/docs/2026-09-18-kal-term-control-design.md

起因

消费者报告 mcpplibs/openkal-musl#36:程序无法进入 raw mode,也无法阻止 Ctrl+C 杀死自己。分析结论:使用侧无责;3/4 是 openkal-musl 端口缺陷,1/4 暴露规范缺口——三平台(Linux/macOS ISIG、Windows ENABLE_PROCESSED_INPUT)都有本机开关一一对应"控制键是否作为数据上交",缺的只是规范里的一个词汇。

方案要点

  • 模式字加 KAL_TERM_CONTROL(位 2):1 = 环境消费控制键(默认);0 = 保证每个键以字节到达,包括 0x03。
  • props 字配套 KAL_TERM_PROP_CONTROL必选。因为恰好对这个位,条款 6.2"未分配读 0"与已发布实现的真实行为(保留 ISIG)不符;依赖保证的程序须先查 props——写入条款 6.2 的规范性例外,由 7.11"声称即能做"原则收口。
  • 独立正交位而非折进 LINE_EDIT:readline 类程序关行编辑但保留控制键打断,三平台皆为本机写法;折叠将违反 7.1 Naturalness。
  • 对使用侧零改动:musl cfmakeraw 本就清 ISIG,端口映射后现有全屏程序自动正确。

任务依赖图

openkal 0.14(规范,硬先行)→ mcpp-index 注册
  → openkal-linux / windows / macos(三实现并行)
  → openkal-musl(最后:ioctl 分发器路由 + ISIG↔CONTROL 映射)

非目标:不改写 openkal 的"无信号"模型;SIG_IGN 静默 no-op 为 openkal-musl 侧独立修复,不在本设计内。

规范文档地址与逐条符合性核对见设计稿 §2.4。

… keystrokes, with the cross-repo plan

A design proposal, no implementation. Full design and task graph in
.agents/docs/2026-09-18-kal-term-control-design.md; arising from consumer
report mcpplibs/openkal-musl#36 (a program cannot enter raw mode or keep
Ctrl+C from killing it).

* The position pair. KAL_TERM_CONTROL (mode word bit 2): 1 = the environment
  consumes reserved control keystrokes, 0 = every keystroke is a byte,
  including 0x03. KAL_TERM_PROP_CONTROL (props word bit 2): the
  implementation distinguishes the position.

* Why a third bit and not a fold into LINE_EDIT. readline turns line
  editing off and keeps control-key interruption on every platform (ICANON
  off + ISIG on; ENABLE_LINE_INPUT off + ENABLE_PROCESSED_INPUT on); the
  orthogonal bit is the native shape and the only 7.1-conformant one.

* Why the props bit is not optional. For this position alone, clause 6.2's
  unassigned-reads-zero does not match released behaviour (openkal-linux
  preserves ISIG): a program that needs the keystrokes-are-data guarantee
  shall enquire kal_terminal_props first. Recorded as the normative
  exception, closed by the claim-is-a-claim principle of clause 7.11.

* The dependency graph. openkal 0.14 (hard first) -> mcpp-index
  registration -> openkal-linux/windows/macos in parallel -> openkal-musl
  last (largest change: the ioctl dispatcher routes to kal_terminal_* and
  cfmakeraw becomes correct for free).

Documents and comments carry no emoji.
@Sunrisepeak

Copy link
Copy Markdown
Member Author

#38 取代并已合并(0.14.0 已发布)。

保留的是这份设计的问题分析、准入论证与依赖序;改掉的是位的极性#38 里位叫 KAL_TERM_PASS_CONTROL,1 = 环境不保留任何按键。这样一来旧实现读回 0 是真话,于是条款 6.2 不需要例外、props 位不需要强制、也没有语义债——本 PR §2.2 要写的那段规范性文字因此消失,换成条款 6.2 里一句可泛化的规则:a position is assigned the sense in which zero is the weaker claim

另外三处在 #38 落地时改了:位的覆盖面是环境保留按键的全部机制(不只 ISIG,否则 ^S 在两个系统上表现不同);关行组装时要确立「读至少等一个字节」(否则 kal_stream_read 会报出一个不是输入结束的 0);KAL_VERSION_MINOR 从 11 校正到 14 并加了 CI 检查。

逐条对照见 .agents/docs/2026-09-20-pr37-term-control-review.md,新方案见 2026-09-20-kal-term-pass-control-design.md

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant